palettize 0.0.1__tar.gz

palettize-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  check-deploy:
+    runs-on: ubuntu-latest
+    outputs:
+      should_deploy: ${{ steps.check.outputs.should_deploy }}
+    steps:
+      - name: Check commit message for [gh-pages]
+        id: check
+        run: |
+          if [[ "${{ github.event.head_commit.message }}" == *"[gh-pages]"* ]] || [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            echo "should_deploy=true" >> $GITHUB_OUTPUT
+          else
+            echo "should_deploy=false" >> $GITHUB_OUTPUT
+          fi
+
+  build:
+    needs: check-deploy
+    if: needs.check-deploy.outputs.should_deploy == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build with Astro
+        uses: withastro/action@v2
+        with:
+          path: docs
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

palettize-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release to PyPI
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  # Nothing reaches PyPI unless the full test, lint, and type-check matrix is green.
+  test:
+    uses: ./.github/workflows/test.yml
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+
+      - name: Verify the built CLI runs
+        run: |
+          uv run --isolated --no-project --with dist/*.whl palettize --version
+          uv run --isolated --no-project --with dist/*.whl palettize formats
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

palettize-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,58 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm derives the version from tags.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run tests with coverage
+        run: >
+          uv run --python ${{ matrix.python-version }} --extra dev
+          pytest --cov=src/palettize --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Ruff lint
+        run: uv run --extra dev ruff check src/ tests/
+
+      - name: Ruff format check
+        run: uv run --extra dev ruff format --check src/ tests/
+
+      - name: Mypy
+        run: uv run --extra dev mypy src/palettize --ignore-missing-imports

palettize-0.0.1/.github/workflows/testindex.yml

@@ -0,0 +1,28 @@
+name: Test release on TestPyPI
+on:
+  push:
+    tags: ['test*']
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+
+      - name: Verify the built CLI runs
+        run: uv run --isolated --no-project --with dist/*.whl palettize --version
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

palettize-0.0.1/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Virtual environments
+.venv
+.ruff_cache/
+.mypy_cache/
+.cursor
+/project_docs/
+.DS_Store
+
+# Docs site build output
+.astro/
+node_modules/
+docs/dist/
+docs/.pagefind/

palettize-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+        # Golden files are compared byte for byte.
+        exclude: ^tests/golden/
+      - id: end-of-file-fixer
+        exclude: ^tests/golden/
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.3
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports]
+        exclude: ^tests/

palettize-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12

palettize-0.0.1/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## [0.0.1] - 2026-09-22
+
+### Added
+
+- `palettize analyze` checks lightness, perceptual step size, and color vision (protanopia, deuteranopia, tritanopia). `--json` prints a report; `--strict` exits non-zero when problems are found.
+- Colormap transforms, each returning a new map: `reversed()`, `cut()`, `resampled()`, `quantized()`, `blend()`, and `concat()` / `+`. The CLI exposes them as `--reverse`, `--cut`, and `--steps`.
+- Portable colormap files. `Colormap.save()` / `load()` and `palettize create --save` write JSON that any command accepts in place of a preset name.
+- `palettize show --output` writes a PNG or SVG preview, with no image library required.
+- Preset discovery: `list presets --search/--category/--namespace/--swatch/--limit`, `list categories`, and `palettize presets <name>`.
+- `palettize formats` lists export formats and the options each one accepts.
+- Bulk sampling (`hex_colors`, `rgb_colors`, `rgba_colors`, `hsl_colors`, `colors`) and colormap protocols (`__call__`, `__len__`, `__iter__`).
+- `palettize info` prints the version, links, and a banner.
+- More `get_color()` formats: `hsl_tuple`, `hsl_string`, `rgb_float`, `rgba_float`, `oklch_string`, `css_color`, plus `output_space="display-p3"`.
+- New exporters: `json`, `css`, `hsl`, `gimp`, and `svg`. `hex` and `rgba` gained output-format options.
+
+### Changed
+
+- Interpolation uses ColorAide, so multi-stop maps follow the correct hue path. Existing maps sample the same colors.
+- `-v` works after a subcommand, and diagnostics go to stderr.
+- `-O` values are coerced from the format's declared options. Unknown keys warn. `palettize formats` says which formats use `--domain` and `--scale`.
+- GDAL omits the comment header unless `-v` is set, and emits an `nv` nodata line unless `-O nodata=false`.
+- Minimum Python is 3.10.
+
+### Fixed
+
+- RGB tuples no longer break later color calls by shadowing ColorAide's `alpha()` method. An alpha of `0.5` on byte RGB stays half-opaque.
+- Colormap files accept only schema version 1. JSON `true`, `0`, and newer versions are refused.
+- SLD no longer builds a reversed `ColorStop` on its fallback path. GEE escapes attribute values.
+- Stop positions are rounded on construction, so chained cuts and a save/load round-trip stay exact.
+- A global `-O` typo warns, the same way a namespaced one does. `nodata=false` suppresses a GDAL nodata line even when `nodata_value` is set.
+- CSS selectors, GIMP palette names, and SVG gradient ids can no longer break out of the file they generate.
+
+### Internal
+
+- Golden-file tests cover every exporter (`pytest --update-golden` to accept an intentional format change). CI runs on `uv` and gates releases on the test matrix.
+- The exporter registry loads on demand. Unused `webcolors` dependency removed.
+
+## [0.0.1a2] - 2025-07-13
+
+### Added
+
+- Support for exporting colormaps to GEE. CSS-like array of strings (default) or GEE-flavored SLD color ramp XML (sld). 
+
+
+
+## [0.0.1a1] - 2025-07-06
+Alpha release of Palettize.
+
+### Added
+
+- Initialized basic project structure, core logic, basic plugin system, and CLI.  
+- Support for creating colormaps from preset palettes from `cmap` dependency.  
+- Support for exporting colormaps to various formats.
+  - GDAL gdaldem color-relief txt format
+  - QGIS color ramp XML
+  - SLD color ramp XML
+  - Titiler url encoded colormap string
+  - Mapgl color interpolation expression  
+  - Observable Plot color object

palettize-0.0.1/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Alex Kovac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

palettize-0.0.1/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: palettize
+Version: 0.0.1
+Summary: A Python CLI and library for previewing, checking, and exporting colormaps.
+Author-email: Alex Kovac <5686693+kovaca@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Documentation, https://kovaca.github.io/palettize
+Project-URL: Repository, https://github.com/kovaca/palettize
+Project-URL: Changelog, https://github.com/kovaca/palettize/blob/main/CHANGELOG.md
+Keywords: colormap,palette,visualization,gis,gdal,qgis,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: coloraide>=4.0
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Requires-Dist: cmap>=0.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-cov>=6.1.1; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# Palettize
+
+🎨 A Python utility and CLI tool for generating, previewing, and exporting colormaps. 
+
+Palettize helps create colormaps for data visualization, GIS, and web mapping. It provides a simple command-line interface to:
+
+-   Generate colormaps from a list of colors or from built-in presets.
+-   Preview colormaps directly in the terminal.
+-   Export colormaps to various formats suitable for different applications.
+-   Customize interpolation color space, data scaling, and slicing.
+
+## Installation
+
+```bash
+# Run it without installing
+uvx palettize show viridis
+
+# Or install it
+uv pip install palettize
+pip install palettize
+```
+
+## Quick tour
+
+```bash
+palettize show viridis                  # preview a colormap in the terminal
+palettize analyze viridis               # check it for perceptual problems
+palettize list presets --search blue    # find a colormap
+palettize formats                       # see the export formats
+palettize create viridis -f gdal -o ramp.txt --domain 0,3000
+```
+
+### Preview
+
+```bash
+palettize show viridis                        # full-width gradient bar
+palettize show viridis --steps 7 --hex        # 7 discrete bands, with hex codes
+palettize show -c "midnightblue,orange,gold"  # a colormap of your own
+palettize show viridis -o preview.png         # write a PNG or SVG instead
+```
+
+### Analyze
+
+`palettize analyze` answers the question that actually matters: is this colormap safe to
+publish? It reports whether lightness increases steadily, whether equal data steps look
+equally different, and how the map degrades for each form of color vision deficiency.
+
+```bash
+palettize analyze cividis
+palettize analyze jet --strict     # exit non-zero when problems are found, for CI
+palettize analyze viridis --json   # machine-readable
+```
+
+```
+cividis  256 stops
+
+  original  ████████████████████████████████████████
+  protan    ████████████████████████████████████████   96% kept   ok
+  deutan    ████████████████████████████████████████   87% kept   ok
+  tritan    ████████████████████████████████████████   72% kept   ok
+
+  lightness    sequential, ascending
+               ▁▁▁▁▂▂▂▂▃▃▃▃▄▄▄▄▅▅▅▅▆▆▆▆▇▇▇▇████
+  range        66 of 100
+  uniformity   variation 0.16 (even)
+  step size    mean 2.8 ΔE, range 1.6-3.7
+
+  No problems detected.
+```
+
+### Export
+
+```bash
+# A GDAL color-relief ramp over your data's actual range
+palettize create viridis -f gdal -o elevation.txt --domain 0,3000
+
+# Several formats at once, with a filename pattern
+palettize create -c "blue,white,red" -f qgis,mapgl \
+  -o "out/{name}_{format}.{ext}" --steps 11 --name RedWhiteBlue
+
+# Non-linear scaling, for skewed data
+palettize create viridis -f gdal --domain 1,10000 --scale log
+
+# Format-specific options
+palettize create viridis -f gdal -O gdal:nodata=false
+```
+
+Run `palettize formats <name>` to see exactly which options a format accepts, with types and
+defaults — no guessing.
+
+### Transform and reuse
+
+Every command accepts `--reverse`, `--cut`, and `--steps`, and any colormap can be saved to a
+portable JSON file and used anywhere a preset name would be:
+
+```bash
+palettize create viridis --cut 0.2,0.8 --reverse --save my-map.json
+palettize show my-map.json
+palettize create my-map.json -f css -o theme.css
+```
+
+## Python API
+
+```python
+from palettize import Colormap, analyze, create_colormap, get_scaler_by_name
+
+cmap = Colormap.from_preset("viridis")
+
+# Sampling
+cmap(0.5)                      # '#21918d'
+cmap.hex_colors(5)             # ['#440154', '#3b528b', '#21918d', '#5cc863', '#fde725']
+cmap.rgb_colors(5)
+len(cmap)                      # 256 stops
+
+# Transforms all return new colormaps
+cmap.reversed()                # name becomes 'viridis_r'
+cmap.cut(0.2, 0.8)             # a sub-range; cuts compose
+cmap.resampled(11)             # refit to 11 evenly spaced stops
+cmap.quantized(5)              # 5 hard-edged bands
+cmap.blend(Colormap.from_preset("magma"), 0.5)
+cmap + Colormap.from_preset("magma")   # concatenate
+
+# Save and reload
+cmap.reversed().save("my-map.json")
+Colormap.load("my-map.json")
+
+# Perceptual analysis
+report = analyze(cmap)
+report.lightness.shape          # 'sequential'
+report.uniformity.is_uniform    # True
+report.warnings                 # plain-language descriptions of any problems
+
+# Map data values onto colors
+scaler = get_scaler_by_name("log", domain_min=1, domain_max=1000)
+cmap.apply_scaler(250, scaler)
+
+# Or start from a list of colors
+create_colormap(colors=["#0000ff", "white", "#ff0000"], name="BlueWhiteRed")
+```
+
+## Export formats
+
+| Format | Identifier | Use case |
+| --- | --- | --- |
+| GDAL color relief | `gdal` | `gdaldem` raster styling |
+| QGIS color ramp | `qgis` | QGIS styles |
+| OGC SLD | `sld` | GeoServer, MapServer |
+| TiTiler | `titiler` | Tile server URL parameter |
+| MapLibre GL | `mapgl` | Web map style expressions |
+| Observable Plot | `observable` | Plot scale definitions |
+| Google Earth Engine | `gee` | GEE JavaScript snippets |
+| CSS | `css` | Custom properties |
+| SVG | `svg` | Gradient definitions |
+| GIMP palette | `gimp` | GIMP, Inkscape, Krita |
+| JSON | `json` | Generic interchange |
+| Hex / RGBA / HSL | `hex`, `rgba`, `hsl` | Plain text color lists |
+
+`palettize formats` lists these with their file extensions; `palettize formats <name>` shows
+each one's options.
+
+## Features
+
+- **~650 presets** from the [`cmap`](https://github.com/tlambert03/cmap) catalog, searchable
+  by name, category, and publisher.
+- **Perceptual interpolation** in any ColorAide space (Oklch by default), with correct hue
+  paths and gamut handling.
+- **Perceptual analysis** built in: lightness monotonicity, ΔE2000 uniformity, and
+  colorblind simulation for protanopia, deuteranopia, and tritanopia.
+- **Composable transforms** — reverse, cut, resample, quantize, blend, concatenate.
+- **Portable colormap files** you can save, share, and feed back into any command.
+- **Plugin system** for third-party export formats via the `palettize.exporters` entry point.
+- **No image dependencies** — PNG output is written with the standard library alone.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest                    # run the tests
+uv run pytest --update-golden    # accept intentional export-format changes
+uv run ruff check src/ tests/
+uv run mypy src/palettize
+```
+
+Exporter output is covered by golden-file tests. When you deliberately change a format, run
+`pytest --update-golden` and review the resulting diff before committing.
+
+## License
+
+MIT