plotform 0.1.0__py3-none-any.whl

plotform/three_d.py

@@ -0,0 +1,40 @@
+"""Minimal styling for Matplotlib's mplot3d axes."""
+
+from __future__ import annotations
+
+from .palette import AXIS, GRID, INK, MUTED, MUTED_AXIS, WHITE
+
+
+def style_3d(
+    ax,
+    *,
+    grid: bool = True,
+    transparent_panes: bool = True,
+    elev: float = 25,
+    azim: float = -55,
+    gray_decorations: bool = False,
+):
+    """Apply the theme's pane, grid, tick, and viewing-angle defaults to 3D axes.
+
+    Matplotlib does not expose these options through the normal 2D rcParams.
+    Call this after creating an axes with ``projection='3d'``.
+    """
+    ax.set_facecolor(WHITE)
+    ax.view_init(elev=elev, azim=azim)
+    ax.grid(grid)
+    axis_color = MUTED_AXIS if gray_decorations else AXIS
+    label_color = MUTED if gray_decorations else INK
+
+    for axis in (ax.xaxis, ax.yaxis, ax.zaxis):
+        if transparent_panes:
+            axis.set_pane_color((1.0, 1.0, 1.0, 0.0))
+        else:
+            axis.set_pane_color(WHITE)
+        axis._axinfo["grid"].update(color=GRID, linewidth=0.7)
+        axis._axinfo["axisline"].update(color=axis_color, linewidth=0.8)
+
+    ax.tick_params(axis="both", colors=label_color, labelcolor=label_color, width=0.8, pad=4)
+    return ax
+
+
+__all__ = ["style_3d"]

plotform-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: plotform
+Version: 0.1.0
+Summary: A minimalist Matplotlib theme and plotting toolkit with customizable palettes, capsule-shaped chart elements, and bundled fonts.
+Author: Econ01
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Econ01/plotform
+Project-URL: Repository, https://github.com/Econ01/plotform
+Project-URL: Issues, https://github.com/Econ01/plotform/issues
+Project-URL: Changelog, https://github.com/Econ01/plotform/blob/main/CHANGELOG.md
+Keywords: matplotlib,plotting,visualization,theme,capsule,publication
+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 :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: fonttools>=4.50; extra == "dev"
+Requires-Dist: pillow>=9; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# Plotform
+
+[![CI](https://github.com/Econ01/plotform/actions/workflows/ci.yml/badge.svg)](https://github.com/Econ01/plotform/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/plotform.svg)](https://pypi.org/project/plotform/)
+[![Python](https://img.shields.io/pypi/pyversions/plotform.svg)](https://pypi.org/project/plotform/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**A minimalist Matplotlib theme and plotting toolkit with customizable palettes, capsule-shaped chart elements, and bundled fonts.**
+
+Plotform combines a vivid, minimalist visual style with native-style helpers for pill legends, circularly rounded bars, capsule annotations, vertical capsule colorbars, and clean 3D plots. Fonts are bundled, so system font installation is not required.
+
+[![Plotform examples showing a line chart, rounded bars, a heatmap, and a 3D scatter plot](https://raw.githubusercontent.com/Econ01/plotform/main/docs/images/overview.png)](https://github.com/Econ01/plotform/tree/main/examples)
+
+## Requirements
+
+- Python 3.10 or newer
+- Matplotlib 3.8 or newer
+- NumPy 1.24 or newer
+
+## Installation
+
+```bash
+python -m pip install plotform
+```
+
+For development from a source checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+import plotform as tm
+
+tm.apply_theme()
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [2, 4, 3], label="Example")
+ax.set(title="A minimalist chart", xlabel="Time", ylabel="Signal")
+tm.legend(ax)
+
+fig.savefig("chart.png", dpi=800)
+fig.savefig("chart.pdf")
+```
+
+`apply_theme()` resets Matplotlib's style before applying Plotform and changes process-global settings. Call it once before creating figures. To preserve and later restore another style, use the scoped form:
+
+```python
+with tm.theme():
+    fig, ax = plt.subplots()
+    ax.plot([1, 2, 3], [2, 4, 3], label="Example")
+    tm.legend(ax)
+    fig.savefig("chart.png")
+# Previous rcParams are restored here.
+```
+
+## Plain Matplotlib, without Plotform
+
+Scripts that must run without the package do not need a compatibility layer. Use native Matplotlib directly:
+
+```python
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+ax.bar([0, 1, 2], [3, 5, 4], label="Example")
+ax.legend()
+fig.savefig("plot.png")
+```
+
+`examples/native_matplotlib.py` is a complete instructor-friendly example. Plotform is an opt-in enhancement, not a requirement for these scripts.
+
+## Native-style helpers
+
+| Helper | Purpose |
+| --- | --- |
+| `tm.legend(ax)` | Solid or soft pill legends with adaptive text contrast |
+| `tm.bar(x, height, ax=ax)` | Vertical bars with circular caps |
+| `tm.barh(y, width, ax=ax)` | Horizontal bars with circular caps |
+| `tm.colorbar(image, ax=ax)` | Vertical capsule colorbar with external ticks |
+| `tm.annotate(text, xy, ax=ax)` | Exact capsule annotation |
+| `tm.style_3d(ax)` | Minimal 3D panes, grids, ticks, and viewing angle |
+
+`legend()` uses the current axes when `ax` is omitted. `colorbar()` uses the current figure and axes. Advanced geometry remains available through `plotform.rounded`; font utilities remain available through `plotform.fonts`.
+
+## Fonts
+
+- **Plotform Sans**, derived from Google Sans Flex with `ROND=100` and default weight 400.
+- **Plotform Mono**, derived from Google Sans Code at its default weight.
+- DejaVu fallbacks for mathematical notation and missing glyphs.
+
+The package registers its bundled fonts directly with Matplotlib. No operating-system installation or cache clearing is needed. Font licenses and attribution are included under `src/plotform/assets/fonts/`.
+
+## Colors
+
+The default vivid categorical cycle is:
+
+| Order | Color | Hex |
+| --- | --- | --- |
+| 1 | Teal | `#008080` |
+| 2 | Amber | `#E69F00` |
+| 3 | Blue | `#0072B2` |
+| 4 | Coral/vermillion | `#D55E00` |
+| 5 | Purple | `#6A51A3` |
+| 6 | Green | `#4C9A2A` |
+| 7 | Rose | `#CC79A7` |
+| 8 | Dark slate | `#4B5563` |
+
+Extend the cycle deterministically:
+
+```python
+tm.apply_theme(n_colors=14)
+colors = tm.get_palette(14)
+```
+
+Axes, labels, and ticks are black by default while grids remain light. For muted-gray decorations:
+
+```python
+tm.apply_theme(gray_decorations=True)
+```
+
+Three continuous colormaps are registered:
+
+```python
+ax.imshow(values, cmap=tm.SCALAR_CMAP)  # Full-range scalar default
+ax.imshow(values, cmap=tm.DIVERGING_CMAP)  # Signed/diverging data
+ax.imshow(values, cmap=tm.SEQUENTIAL_CMAP)  # Optional pale brand-teal map
+```
+
+`SCALAR_CMAP` follows navy → blue → teal → green → amber, avoiding near-white endpoints. Use fully opaque scalar markers and `depthshade=False` for mplot3d scatter plots. Use `shade=True` for `bar3d` to preserve face lighting.
+
+## Pill legends
+
+Solid category-color fills use adaptive white or black text, targeting at least 4.5:1 contrast. Marker and line handles are explicitly hidden so they cannot overlap labels.
+
+```python
+tm.legend(ax, ncols=3)
+```
+
+For auxiliary uncertainty regions, use an explicitly tinted entry:
+
+```python
+tm.legend(ax, styles={"95% interval": "soft"})
+```
+
+For dense plots, place the legend outside or add a white group capsule:
+
+```python
+tm.legend(ax, outside=True)
+tm.legend(ax, backdrop=True, backdrop_alpha=0.88)
+```
+
+## Rounded bars and annotations
+
+```python
+import numpy as np
+
+x = np.arange(4)
+
+# Exact semicircular cap with a square baseline.
+tm.bar(x, [3, 5, -2, 4], radius="full", ends="free", ax=ax)
+
+# Complete vertical capsule.
+tm.bar(x, [3, 5, -2, 4], radius="full", ends="both", ax=ax)
+
+# Clamp bars too short for an exact full capsule.
+tm.bar(x, [3, 5, -2, 4], radius="fit", ends="both", ax=ax)
+
+# Numeric circular corner radius.
+tm.bar(x, [3, 5, -2, 4], radius=0.16, ax=ax)
+```
+
+Exact full mode raises a clear error when the display geometry cannot contain the requested semicircle. Use `radius="fit"` to opt into clamping instead.
+
+Annotations use exact stadium geometry:
+
+```python
+tm.annotate("New", (0.15, 0.85), ax=ax, transform=ax.transAxes)
+```
+
+`plotform.rounded` also exposes `capsule_path`, `CapsuleBox`, and separate squircle primitives for advanced use.
+
+[![Exact horizontal and vertical capsule geometry](https://raw.githubusercontent.com/Econ01/plotform/main/docs/images/capsules.png)](https://github.com/Econ01/plotform/blob/main/examples/geometry_check.py)
+
+## Capsule colorbars
+
+```python
+image = ax.imshow(values, cmap=tm.SCALAR_CMAP)
+colorbar = tm.colorbar(image, ax=ax)
+```
+
+The visible gradient is clipped to an exact vertical capsule in display space. Ticks and labels remain outside. Image, contour, streamplot, scatter, and surface mappables are supported. Standard rectangular `fig.colorbar()` output remains available.
+
+## 3D plots
+
+```python
+fig = plt.figure()
+ax = fig.add_subplot(projection="3d")
+tm.style_3d(ax)
+ax.plot_surface(xx, yy, zz, cmap=tm.DIVERGING_CMAP, shade=True)
+```
+
+`style_3d()` clears panes and applies consistent grids, ticks, and viewing geometry. Pass `gray_decorations=True` for muted decorations.
+
+## Visual showcase
+
+```bash
+python examples/showcase.py
+python examples/geometry_check.py
+```
+
+The showcase creates 27 default-versus-Plotform comparisons at 800 DPI, lightweight previews, selected PDF/SVG exports, and a contact sheet under `artifacts/showcase/`. The geometry script creates exact capsule reference boards under `artifacts/`.
+
+[View the complete 27-chart contact sheet](https://github.com/Econ01/plotform/blob/main/docs/images/contact-sheet.png) or regenerate the documentation images with `python tools/make_doc_images.py`.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+python -m build
+```
+
+See `CHANGELOG.md` for release history and `docs/RELEASING.md` for the GitHub, TestPyPI, and PyPI release process.
+
+## License
+
+Code is MIT licensed. Bundled font software remains under the SIL Open Font License; see the font asset notices for details.

plotform-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+plotform/__init__.py,sha256=i4nQUfib-fgCxmsK-nU4L8JPf6RjxX1YzBEAmyQYEaU,967
+plotform/api.py,sha256=UaQcmYA8eAp43reXUmSyXxSIpZXrtOtXfs-rldCd21M,1390
+plotform/colorbar_utils.py,sha256=gTB-X_3nn_tjl1ZvSP-4xwuw_SjUyatP95aunwFrTAY,2323
+plotform/fonts.py,sha256=KRknHc7Y-kCimhdWqlvK5MK0MrTLelyxutkU7bkLNM8,1821
+plotform/legend_utils.py,sha256=oFdvbJeD5f_SqhVSxe_3sEEV9vi8GnwN3pOzaknUuPw,6748
+plotform/palette.py,sha256=92ceATHZa1N4Ae4aVidR7eGlFoqHV0HdF4OLrMS7loM,3210
+plotform/rounded.py,sha256=6Lf_IJM3DoDMfLkDfmbbz1oZENTzRQ5NdIToCWLgqd0,15917
+plotform/theme.py,sha256=15LVcgvG63xYIS0GGQucEbutHUk3pXHI3ouPTe9xsKk,5761
+plotform/three_d.py,sha256=GeEutJ4X3Qdhr5bvZahVi-UmpD3mCEVWXQL9xMjzKT0,1210
+plotform/assets/fonts/PlotformMono-OFL.txt,sha256=_49PvE8accfUxkgcSNwrIcQ_jcFYclNmZ_7kXBXSCSg,4396
+plotform/assets/fonts/PlotformMono-Regular.ttf,sha256=RewGQyko36BxZl2oFhHOPGRR4NeyI13cqIxa3rlXQx4,54728
+plotform/assets/fonts/PlotformMono-TRADEMARKS.md,sha256=2cYnyWiDe0oUgZUVMnHKaemNS8dQsEHg2Yuns3axz1A,1478
+plotform/assets/fonts/PlotformSans-OFL.txt,sha256=_BPWn2PjbShLbjg9TRRj2K1ATwqgZeV8-WElLVEGMTc,4488
+plotform/assets/fonts/PlotformSans-Rounded.ttf,sha256=B-gp5oa3a7mtZqrgziLCJ7pLxfnFDlyGmt-V_07h3B0,135908
+plotform/assets/fonts/PlotformSans-TRADEMARKS.md,sha256=XK04HAgo22VvMqeHoe_3bbMwPHTsT5Rmiun8KHP_5C8,1585
+plotform/assets/fonts/README.md,sha256=NJGqx8G7iyZHb1qzJNPMVrdOjOwJoD7iGZnnI4sOKAA,1477
+plotform-0.1.0.dist-info/licenses/LICENSE,sha256=CyF9C-jwz6-vCay6i5Ogbx5FcVFBsojgk0KC5E62b_o,1213
+plotform-0.1.0.dist-info/METADATA,sha256=Aj9_88e1tY2SSfGWi-bhjnZW9CA2pO0jEtlRjVkmTXs,9410
+plotform-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+plotform-0.1.0.dist-info/top_level.txt,sha256=AbbFIaqd-8jLb_RtYmaTRXjqZXmskJGnOM9aBVlABZM,9
+plotform-0.1.0.dist-info/RECORD,,

plotform-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

plotform-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Econ01
+
+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.
+
+Bundled font software is licensed separately under the SIL Open Font License.
+See src/plotform/assets/fonts/ for the font licenses and attributions.

plotform-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+plotform