hilbertplot 0.1.0__tar.gz → 1.0.0__tar.gz

hilbertplot-1.0.0/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to **hilbertplot** are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
+[Semantic Versioning](https://semver.org/).
+
+Released versions below are generated automatically by python-semantic-release;
+new entries are inserted at the marker.
+
+## Local API redesign (unreleased)
+
+- Make array conversion lossless for dtypes, large integers, complex values and
+  masks; keep padding masked where NaN would require lossy integer conversion.
+- Convert supported square and quasisquare arrays to flat 1-D sequences,
+  retaining RGB/RGBA channel order; restore with `to_grid(..., shape=original.shape)`.
+  Reject general rectangles and unsupported curve/shape combinations without a
+  fallback. Add explicit `from_grid(..., length=...)` prefix handling.
+- Run the release build hook after semantic version stamping to regenerate and
+  commit `uv.lock` automatically. Verify title-driven patch/minor/breaking releases
+  in disposable repositories in CI; versions remain semantic-release-owned.
+- Allow `plot_curve(..., shape=(rows, columns))` to draw supported arbitrary
+  squares and quasisquares directly as lines. Select a connected quasisquare
+  orientation internally. `curves.grid` also accepts the same shape pair.
+- Use `hp.data.to_grid` / `from_grid` and `hp.curves.index_to_xy` /
+  `xy_to_index` for explicit mapping directions. Remove the former `image`,
+  `unroll`, `encode`, and `decode` aliases from these namespaces.
+- Keep top-level completion to `plot`, `plot_curve`, `gallery`, `curves`, `data`,
+  and `config`. Move metadata/geometry, array operations, and resource controls
+  into their respective module namespaces; remove their top-level aliases.
+- Add `examples/try_api.py` to exercise the complete function-based interface.
+- Add data-first `plot(data, curve=...)` and `plot_curve(curve, order=...)`.
+  Each call returns a standard Matplotlib Figure, without opening a window.
+- Keep `fourier=False` and `difference=False` as mutually exclusive flags on
+  `plot`; difference mode displays the full geometric field instead of a threshold overlay.
+- Keep custom classes internal. Remove the `Curve`, `CurveList`, `HilbertPlot`,
+  and `hilbert_plot` exports. Curve metadata and groups return plain dicts/lists.
+- Expose array, coordinate, and indexing operations as functions; retain the
+  numpy-only computational path. See the README migration table for replacements.
+- Default new data functions to power-of-two padding; require explicit truncation
+  when an order is too small. Reject ambiguous multidimensional/complex input,
+  handle masked integer data, and report invalid Fourier inputs without warnings.
+- Normalize the memory regression test's RSS units on macOS as well as Linux.
+
+These changes are under local review and have not been released.
+
+## Migrating from 0.1.0
+
+`hilbertplot` is on `0.x`, where [semver §4](https://semver.org/#spec-item-4) allows the
+interface to change in a minor release. Two spellings changed; both fail loudly rather
+than silently, and nothing else in the 0.1.0 surface was removed.
+
+| 0.1.0 | now | why |
+| --- | --- | --- |
+| `curve.plot(order)` | `curve.draw(order)` | one verb for "render onto axes", shared with `HilbertPlot.draw` |
+| `curve.save(order, path)` | `curve.save(path, order)` | matches `HilbertPlot.save(path, ...)`; the old order raises a `TypeError` naming the fix |
+| `repr(curve)` → `'Hilbert'` | `repr(curve)` → `'<Curve 0H Hilbert (proper)>'` | `repr` is now unambiguous; `str(curve)` is still `'Hilbert'` |
+
+Behaviour that was buggy and is now stricter: `curve(True)` and `curve(3.0)` raise
+`TypeError` instead of silently meaning `curve(1)` / `curve(3)`; an out-of-range index
+raises `IndexError` rather than `KeyError` (both are `LookupError`); `plot.data` is
+genuinely immutable rather than merely flagged; and `image(order=..., fit=...)` now
+validates `fit` instead of ignoring it.
+
+<!-- version list -->
+
+## v1.0.0 (2026-11-01)
+
+### Features
+
+- Simplify plotting and add lossless curve conversions
+  ([`f45f2a6`](https://github.com/El3ssar/hilbertplot/commit/f45f2a6219bfc1f6259d72a64d01c8b19ae7d28e))
+
+### Breaking Changes
+
+- Replace public curve/plot objects and top-level numerical helpers with function-based plotting and
+  namespaced to_grid/from_grid/index_to_xy/xy_to_index operations. Data plots default to
+  power-of-two padding; difference=True renders the full locality-loss field. General rectangles are
+  intentionally unsupported.
+
+
+## v0.2.0 (2026-07-25)
+
+### Bug Fixes
+
+- Close the gaps found by the second review round
+  ([`9df64f4`](https://github.com/El3ssar/hilbertplot/commit/9df64f463b2619d0d19ca7d3d818a16e2c25d7d8))
+
+- Keep the new guards from costing more than they save
+  ([`bbaa464`](https://github.com/El3ssar/hilbertplot/commit/bbaa4646af8ca401aa27174277cbae22910cd34f))
+
+### Continuous Integration
+
+- Bump actions, exempt dependabot from title check, curb ruff bumps
+  ([`aa74d78`](https://github.com/El3ssar/hilbertplot/commit/aa74d7810fa542e259dfcee77c23ad9aa491374a))
+
+- Stop Dependabot from bumping ruff
+  ([`f639fc0`](https://github.com/El3ssar/hilbertplot/commit/f639fc0aa5ab67c615bf31470cfd1bd10f5248b5))
+
+- Stop the floors job re-resolving the pins it exists to test
+  ([`106b08f`](https://github.com/El3ssar/hilbertplot/commit/106b08f8bedcf0d6c2c0ff023a60c2ff020265e4))
+
+### Documentation
+
+- Add status badges and tidy the 0.1.0 changelog entry
+  ([`7d967ca`](https://github.com/El3ssar/hilbertplot/commit/7d967caae998903d0885a81c4801b50b974aef62))
+
+- Illustrate the README with generated figures
+  ([`0f245b9`](https://github.com/El3ssar/hilbertplot/commit/0f245b941fbb933141b10d60ee16157c463b8501))
+
+- Streamline the README to install + two examples
+  ([`fb53eab`](https://github.com/El3ssar/hilbertplot/commit/fb53eab38129a8e60c42160d5bfa3959677a37db))
+
+### Features
+
+- Make the arbitrary-square path fast, harden the public surface, add encode/decode
+  ([`a6ce0da`](https://github.com/El3ssar/hilbertplot/commit/a6ce0da3463acaacc6c69d349a1ef06804a817f4))
+
+
+## v0.1.0 (2026-07-25)
+
+First public release — the complete set of 40 two-dimensional Hilbert curves,
+with fast numpy generation and data-visualisation tooling.
+
+### Added
+- The complete set of **40** two-dimensional Hilbert curves (Estevez-Rams et al., 2017):
+  `curve(i)` by index, name or symbol; `points(order)`, `word(order)`; family groups
+  `homogeneous` / `inhomogeneous` / `proper` / `improper` / `closed` / `by_kernels`,
+  returned as a `CurveList` that prints as a table.
+- Fast numpy stroke-code generation (no per-stroke Python loop); order-10 curve (~1M
+  points) in tens of milliseconds.
+- Curve rendering: `curve.show/save/plot(order)` with automatic line→fill mode by order,
+  colour-graded traversal, and `gallery()` for grids of curves.
+- **Data visualisation** ("Hilbert plots", Estevez-Rams et al., 2015): `hilbert_plot`
+  / `curve.plot_data` return a `HilbertPlot` that maps a 1-D vector onto 2-D on demand,
+  with colormap-by-name or colour-list interpolation, the `l`-granularity transform,
+  and `pad` / `truncate` fits.
+- **Difference map** overlay (`difference=True`, tunable threshold) marking where a curve
+  breaks locality (Pérez-Demydenko et al., 2014); `curve.difference_map(order)`.
+- **2-D Fourier map** (`fourier=True`; `HilbertPlot.fourier()`) revealing hidden periodic
+  and self-similar structure.
+- **`unroll`**: read a 2-D square array back into a 1-D vector in curve order.
+- **Arbitrary `n x n` squares** for the eight curves that support it
+  (`curve.grid(n)`, `curve.generalizes`, `hilbertplot.generalizing()`); the data mapping
+  square-fits to a tight `ceil(sqrt(N))` grid by default for those curves. The full
+  feasibility classification and impossibility proofs are in `research/quasisquares/`.
+
+### Notes
+- Requires Python 3.10+. `numpy` is the only runtime dependency; `matplotlib` is the
+  optional `[plot]` extra.

hilbertplot-1.0.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: hilbertplot
+Version: 1.0.0
+Summary: The complete set of 40 two-dimensional Hilbert curves, and data plots on them.
+Project-URL: Homepage, https://github.com/El3ssar/hilbertplot
+Project-URL: Source, https://github.com/El3ssar/hilbertplot
+Project-URL: Issues, https://github.com/El3ssar/hilbertplot/issues
+Project-URL: Changelog, https://github.com/El3ssar/hilbertplot/blob/main/CHANGELOG.md
+Author-email: Daniel Estevez <kemossabee@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dimensionality-reduction,hilbert-curve,locality,moore-curve,space-filling-curve,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.21
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff==0.15.13; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# hilbertplot
+
+[![PyPI version](https://img.shields.io/pypi/v/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![CI](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml/badge.svg)](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Plot long numeric sequences on any of **40 two-dimensional Hilbert-type curves**.
+Choose a curve by number, label, or paper symbol. The interface is functions returning
+ordinary arrays, dictionaries, lists, and Matplotlib figures; custom classes stay internal.
+
+Top-level completion has just six entries: `plot`, `plot_curve`, `gallery`,
+`curves`, `data`, and `config`. Specialist functions live under those three namespaces:
+`hp.curves` for the catalog and geometry, `hp.data` for arrays, and `hp.config` for
+optional cache and allocation controls.
+
+## Install
+
+```bash
+pip install "hilbertplot[plot]"   # omit [plot] for numpy-only operations
+```
+
+## Plot your data
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import hilbertplot as hp
+
+data = np.sin(np.arange(1000) / 10)
+fig = hp.plot(data)                       # standard Hilbert curve
+fig = hp.plot(data, curve=12)             # any curve index 0..39
+fig = hp.plot(data, curve="Moore")        # or a label; "12H" also works
+fig.savefig("data.png", dpi=200)
+plt.show()                               # display figures in a script
+```
+
+Each call makes **one plot** and returns a Matplotlib `Figure`. No window is opened
+implicitly. Use `ax=` to draw on your own Matplotlib axes. Figures remain open until
+you close them with `plt.close(fig)`.
+
+## Fourier, difference, and granularity maps
+
+```python
+fig = hp.plot(data, fourier=True)          # centred 2-D Fourier magnitude
+fig = hp.plot(data, difference=True)       # full locality-loss field
+fig = hp.plot(data, granularity=16)        # average consecutive blocks of 16
+fig = hp.plot(data, fourier=True, granularity=16, window=True)
+```
+
+`fourier` and `difference` are boolean flags, both off by default (`False` / `0`).
+They are **mutually exclusive**: setting both raises `ValueError`.
+
+- **Fourier:** transforms the mapped 2-D image, not the original 1-D signal. Defaults
+  to `log1p(abs(FFT))` with the mean subtracted. Use `log=False` for raw magnitude,
+  `remove_dc=False` to retain the mean, or `window=True` for a Hann window.
+- **Difference:** displays the mean absolute visit-index distance to each cell's up-to-eight
+  neighbours. It describes the curve's geometry, independently of data values.
+- **Granularity:** replaces each consecutive sequence block by copies of its mean.
+  The sequence and image retain their sizes; this is not image downsampling. It affects
+  the data and its Fourier transform. Geometry-based difference maps stay unchanged.
+
+## Draw a curve
+
+```python
+fig = hp.plot_curve(12, order=4)
+fig = hp.plot_curve("Moore", order=4, color="steelblue")
+fig = hp.plot_curve(0, order=8, mode="fill")
+
+# Arbitrary square and quasisquare: draw the path itself, with no data.
+fig = hp.plot_curve(3, shape=(15, 15), mode="line")
+fig = hp.plot_curve(3, shape=(15, 16), mode="line")
+fig = hp.plot_curve(3, shape=(16, 15), mode="line")
+```
+
+`order=k` visits `4**k` cells in a `2**k` square. Curve drawing automatically switches
+from coloured lines to a filled visit-order image at order 8. Explicit `mode="line"`
+or `"fill"`, `linewidth`, and endpoint markers are also available.
+
+`shape=(rows, columns)` selects explicit dimensions instead of an order. A
+quasisquare's sides differ by one. Arbitrary squares and quasisquares require one
+of curves **0, 3, 4, 5, 24, 29, 30, 31**. Quasisquare orientation is selected
+automatically to keep every step connected. Use either `shape` or `order`, not both.
+`hp.curves.grid((rows, columns), curve=...)` returns the same path as coordinates.
+
+## Colour and fitting
+
+```python
+from matplotlib.colors import LogNorm
+
+fig = hp.plot(np.arange(1, 1001), norm=LogNorm(), colorbar=True)
+fig = hp.plot(data, cmap=["navy", "white", "firebrick"], vmin=-1, vmax=1)
+compact = hp.data.to_grid(data, fit="square")      # supported curves only
+```
+
+`hp.plot()` and `hp.data.to_grid()` share these layout choices:
+
+| `fit` | Behaviour |
+| --- | --- |
+| `"pad"` (default) | Smallest enclosing power-of-two square; works with every curve |
+| `"square"` | Tight `ceil(sqrt(N))` square; only the eight generalizing curves |
+| `"auto"` | Tight square where supported, otherwise power-of-two padding |
+| `"truncate"` | Largest power-of-two square inside the data; explicitly discards the tail |
+
+Padding is NaN and appears transparent. `order=` fixes the grid; if it is too small,
+the call raises unless you explicitly choose `fit="truncate"`. Pass either `norm=`
+or `vmin`/`vmax`, not both. Extra Matplotlib image options such as `alpha` are supported.
+
+## Arrays and index maths (no Matplotlib needed)
+
+```python
+img = hp.data.to_grid(data, curve=12)
+spectrum = hp.data.fourier(data, curve=12, window=True)
+recovered = hp.data.from_grid(img, curve=12, length=len(data))
+labels = hp.curves.label_map(12, side=img.shape[0])
+differences = hp.curves.difference_map(12, side=img.shape[0])
+
+pts = hp.curves.points(12, order=4)              # (256, 2) array of (x, y) cells
+word = hp.curves.word(12, order=4)               # u/d/l/r strokes
+arbitrary = hp.curves.grid(100, curve=0)         # arbitrary square, supported curves only
+xy = hp.curves.index_to_xy(10**18, 40, curve=12)      # O(order), no full-grid allocation
+assert hp.curves.xy_to_index(*xy, 40, curve=12) == 10**18
+assert hp.curves.is_space_filling(pts, 16)
+key = hp.curves.canonical_form(pts)             # compare paths up to symmetry/reversal
+```
+
+Images are indexed `[y, x]`; coordinates are `(x, y)`. Plotting and Fourier maps
+accept real, nonempty scalar sequences; choose magnitude, phase, real or imaginary
+values explicitly for complex data. Plotting rejects infinities. NaNs propagate
+through granularity block means; Fourier maps mean-fill missing cells and require
+at least one finite value.
+
+Array conversion is separate from display: `to_grid()` / `from_grid()` preserve
+numeric dtypes, complex values, large integers, and masks. With no padding or
+averaging, conversion is exact. Default NaN padding keeps floating/complex dtypes;
+integer and boolean padding uses a NumPy masked array to retain precision. Use
+`fill=0` for ordinary integer padding. `length=` explicitly selects a prefix without
+deleting legitimate NaNs or masked values.
+
+```python
+# A square RGB image becomes a truly 1-D sequence. Each pixel's channels
+# stay consecutive; use the full original shape when reconstructing.
+rgb = np.arange(16 * 16 * 3, dtype=np.uint16).reshape(16, 16, 3)
+sequence = hp.data.from_grid(rgb, curve=12)
+assert sequence.ndim == 1 and sequence.size == rgb.size
+restored = hp.data.to_grid(sequence, curve=12, shape=rgb.shape)
+np.testing.assert_array_equal(restored, rgb)
+assert restored.dtype == rgb.dtype
+
+# The same functions use exact quasisquare paths for supported curves.
+square_or_quasisquare = np.arange(15 * 16).reshape(15, 16)
+sequence = hp.data.from_grid(square_or_quasisquare, curve=3)
+restored = hp.data.to_grid(sequence, curve=3, shape=square_or_quasisquare.shape)
+np.testing.assert_array_equal(restored, square_or_quasisquare)
+```
+
+Conversion uses the same connected path as `plot_curve(shape=...)`. Spatial
+shapes must be supported squares or quasisquares; general rectangles are not
+supported. Unsupported shapes raise an error without padding or cropping them
+into a different traversal. `shape=` specifies the output's original dimensions;
+it cannot be combined with `order=`. Converting a grid with another curve gives a
+reversible reordering; keep all entries, including padding, when reversing it.
+
+## Discover curves
+
+```python
+info = hp.curves.info(12)                       # ordinary metadata dictionary
+print(info["name"], info["index"], info["kernels"])
+print([(c["index"], c["name"]) for c in hp.curves.catalog()])
+print([c["index"] for c in hp.curves.generalizing()])
+fig = hp.gallery(hp.curves.by_kernels(3, 5), order=3)
+```
+
+Under `hp.curves`, `catalog()` lists all 40 curves: 6 `proper()`, 6 `improper()` (together 12
+`homogeneous()`), and 28 `inhomogeneous()`. Groups return ordinary lists of metadata
+dictionaries. `closed()` lists the four loops; `generalizing()` lists curves
+0, 3, 4, 5, 24, 29, 30, and 31, which support arbitrary square sizes.
+
+Under `hp.config`, `clear_cache()` releases cached generation data, and `cache_info()`
+reports its use.
+`cell_limit()` / `set_cell_limit(n)` control the allocation guard. Grid size grows
+exponentially with order; the default limit is a ceiling, not a memory reservation.
+
+More runnable examples are in [examples/](examples/). The curve classification follows
+Estevez-Rams et al., *Hilbert curves in two dimensions*, Rev. Cub. Fís. **34**, 9 (2017).
+The arbitrary-square research is in [research/quasisquares/](research/quasisquares/).
+
+## Try all the features
+
+The [complete runnable example](examples/try_api.py) draws separate figures for the
+curve, data, coarse-grained data, Fourier and difference maps, colour options, fitting
+modes, and a gallery. It also checks numeric round trips, geometry, indexing and groups.
+
+```bash
+python examples/try_api.py
+# Save figures and run all checks without opening windows:
+MPLBACKEND=Agg python examples/try_api.py --save-only
+```
+
+Figures are saved in `examples/output/try_api/`.
+
+## Local API migration
+
+This working-tree redesign replaces the object-based 0.2.0 interface:
+
+| Previous | New |
+| --- | --- |
+| `hilbert_plot(12, data).draw()` | `plot(data, curve=12)` |
+| `curve(12).draw(4)` | `plot_curve(12, order=4)` |
+| `plot.save(path)` | `fig = plot(data); fig.savefig(path)` |
+| `curve(12).points(4)` | `hp.curves.points(12, order=4)` |
+| `curve(12).unroll(img)` | `hp.data.from_grid(img, curve=12)` |
+| `curve(12).name` | `hp.curves.info(12)["name"]` |
+| `proper().names` | `[c["name"] for c in hp.curves.proper()]` |
+
+The old `Curve`, `CurveList`, `HilbertPlot`, and `hilbert_plot` exports are removed.
+`difference=True` now renders the complete difference map. Rendering defaults to
+power-of-two padding. These are intentional interface changes under local review.
+
+## License
+
+MIT © Daniel Estevez — [LICENSE](LICENSE).

hilbertplot-1.0.0/README.md

@@ -0,0 +1,222 @@
+# hilbertplot
+
+[![PyPI version](https://img.shields.io/pypi/v/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![CI](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml/badge.svg)](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Plot long numeric sequences on any of **40 two-dimensional Hilbert-type curves**.
+Choose a curve by number, label, or paper symbol. The interface is functions returning
+ordinary arrays, dictionaries, lists, and Matplotlib figures; custom classes stay internal.
+
+Top-level completion has just six entries: `plot`, `plot_curve`, `gallery`,
+`curves`, `data`, and `config`. Specialist functions live under those three namespaces:
+`hp.curves` for the catalog and geometry, `hp.data` for arrays, and `hp.config` for
+optional cache and allocation controls.
+
+## Install
+
+```bash
+pip install "hilbertplot[plot]"   # omit [plot] for numpy-only operations
+```
+
+## Plot your data
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import hilbertplot as hp
+
+data = np.sin(np.arange(1000) / 10)
+fig = hp.plot(data)                       # standard Hilbert curve
+fig = hp.plot(data, curve=12)             # any curve index 0..39
+fig = hp.plot(data, curve="Moore")        # or a label; "12H" also works
+fig.savefig("data.png", dpi=200)
+plt.show()                               # display figures in a script
+```
+
+Each call makes **one plot** and returns a Matplotlib `Figure`. No window is opened
+implicitly. Use `ax=` to draw on your own Matplotlib axes. Figures remain open until
+you close them with `plt.close(fig)`.
+
+## Fourier, difference, and granularity maps
+
+```python
+fig = hp.plot(data, fourier=True)          # centred 2-D Fourier magnitude
+fig = hp.plot(data, difference=True)       # full locality-loss field
+fig = hp.plot(data, granularity=16)        # average consecutive blocks of 16
+fig = hp.plot(data, fourier=True, granularity=16, window=True)
+```
+
+`fourier` and `difference` are boolean flags, both off by default (`False` / `0`).
+They are **mutually exclusive**: setting both raises `ValueError`.
+
+- **Fourier:** transforms the mapped 2-D image, not the original 1-D signal. Defaults
+  to `log1p(abs(FFT))` with the mean subtracted. Use `log=False` for raw magnitude,
+  `remove_dc=False` to retain the mean, or `window=True` for a Hann window.
+- **Difference:** displays the mean absolute visit-index distance to each cell's up-to-eight
+  neighbours. It describes the curve's geometry, independently of data values.
+- **Granularity:** replaces each consecutive sequence block by copies of its mean.
+  The sequence and image retain their sizes; this is not image downsampling. It affects
+  the data and its Fourier transform. Geometry-based difference maps stay unchanged.
+
+## Draw a curve
+
+```python
+fig = hp.plot_curve(12, order=4)
+fig = hp.plot_curve("Moore", order=4, color="steelblue")
+fig = hp.plot_curve(0, order=8, mode="fill")
+
+# Arbitrary square and quasisquare: draw the path itself, with no data.
+fig = hp.plot_curve(3, shape=(15, 15), mode="line")
+fig = hp.plot_curve(3, shape=(15, 16), mode="line")
+fig = hp.plot_curve(3, shape=(16, 15), mode="line")
+```
+
+`order=k` visits `4**k` cells in a `2**k` square. Curve drawing automatically switches
+from coloured lines to a filled visit-order image at order 8. Explicit `mode="line"`
+or `"fill"`, `linewidth`, and endpoint markers are also available.
+
+`shape=(rows, columns)` selects explicit dimensions instead of an order. A
+quasisquare's sides differ by one. Arbitrary squares and quasisquares require one
+of curves **0, 3, 4, 5, 24, 29, 30, 31**. Quasisquare orientation is selected
+automatically to keep every step connected. Use either `shape` or `order`, not both.
+`hp.curves.grid((rows, columns), curve=...)` returns the same path as coordinates.
+
+## Colour and fitting
+
+```python
+from matplotlib.colors import LogNorm
+
+fig = hp.plot(np.arange(1, 1001), norm=LogNorm(), colorbar=True)
+fig = hp.plot(data, cmap=["navy", "white", "firebrick"], vmin=-1, vmax=1)
+compact = hp.data.to_grid(data, fit="square")      # supported curves only
+```
+
+`hp.plot()` and `hp.data.to_grid()` share these layout choices:
+
+| `fit` | Behaviour |
+| --- | --- |
+| `"pad"` (default) | Smallest enclosing power-of-two square; works with every curve |
+| `"square"` | Tight `ceil(sqrt(N))` square; only the eight generalizing curves |
+| `"auto"` | Tight square where supported, otherwise power-of-two padding |
+| `"truncate"` | Largest power-of-two square inside the data; explicitly discards the tail |
+
+Padding is NaN and appears transparent. `order=` fixes the grid; if it is too small,
+the call raises unless you explicitly choose `fit="truncate"`. Pass either `norm=`
+or `vmin`/`vmax`, not both. Extra Matplotlib image options such as `alpha` are supported.
+
+## Arrays and index maths (no Matplotlib needed)
+
+```python
+img = hp.data.to_grid(data, curve=12)
+spectrum = hp.data.fourier(data, curve=12, window=True)
+recovered = hp.data.from_grid(img, curve=12, length=len(data))
+labels = hp.curves.label_map(12, side=img.shape[0])
+differences = hp.curves.difference_map(12, side=img.shape[0])
+
+pts = hp.curves.points(12, order=4)              # (256, 2) array of (x, y) cells
+word = hp.curves.word(12, order=4)               # u/d/l/r strokes
+arbitrary = hp.curves.grid(100, curve=0)         # arbitrary square, supported curves only
+xy = hp.curves.index_to_xy(10**18, 40, curve=12)      # O(order), no full-grid allocation
+assert hp.curves.xy_to_index(*xy, 40, curve=12) == 10**18
+assert hp.curves.is_space_filling(pts, 16)
+key = hp.curves.canonical_form(pts)             # compare paths up to symmetry/reversal
+```
+
+Images are indexed `[y, x]`; coordinates are `(x, y)`. Plotting and Fourier maps
+accept real, nonempty scalar sequences; choose magnitude, phase, real or imaginary
+values explicitly for complex data. Plotting rejects infinities. NaNs propagate
+through granularity block means; Fourier maps mean-fill missing cells and require
+at least one finite value.
+
+Array conversion is separate from display: `to_grid()` / `from_grid()` preserve
+numeric dtypes, complex values, large integers, and masks. With no padding or
+averaging, conversion is exact. Default NaN padding keeps floating/complex dtypes;
+integer and boolean padding uses a NumPy masked array to retain precision. Use
+`fill=0` for ordinary integer padding. `length=` explicitly selects a prefix without
+deleting legitimate NaNs or masked values.
+
+```python
+# A square RGB image becomes a truly 1-D sequence. Each pixel's channels
+# stay consecutive; use the full original shape when reconstructing.
+rgb = np.arange(16 * 16 * 3, dtype=np.uint16).reshape(16, 16, 3)
+sequence = hp.data.from_grid(rgb, curve=12)
+assert sequence.ndim == 1 and sequence.size == rgb.size
+restored = hp.data.to_grid(sequence, curve=12, shape=rgb.shape)
+np.testing.assert_array_equal(restored, rgb)
+assert restored.dtype == rgb.dtype
+
+# The same functions use exact quasisquare paths for supported curves.
+square_or_quasisquare = np.arange(15 * 16).reshape(15, 16)
+sequence = hp.data.from_grid(square_or_quasisquare, curve=3)
+restored = hp.data.to_grid(sequence, curve=3, shape=square_or_quasisquare.shape)
+np.testing.assert_array_equal(restored, square_or_quasisquare)
+```
+
+Conversion uses the same connected path as `plot_curve(shape=...)`. Spatial
+shapes must be supported squares or quasisquares; general rectangles are not
+supported. Unsupported shapes raise an error without padding or cropping them
+into a different traversal. `shape=` specifies the output's original dimensions;
+it cannot be combined with `order=`. Converting a grid with another curve gives a
+reversible reordering; keep all entries, including padding, when reversing it.
+
+## Discover curves
+
+```python
+info = hp.curves.info(12)                       # ordinary metadata dictionary
+print(info["name"], info["index"], info["kernels"])
+print([(c["index"], c["name"]) for c in hp.curves.catalog()])
+print([c["index"] for c in hp.curves.generalizing()])
+fig = hp.gallery(hp.curves.by_kernels(3, 5), order=3)
+```
+
+Under `hp.curves`, `catalog()` lists all 40 curves: 6 `proper()`, 6 `improper()` (together 12
+`homogeneous()`), and 28 `inhomogeneous()`. Groups return ordinary lists of metadata
+dictionaries. `closed()` lists the four loops; `generalizing()` lists curves
+0, 3, 4, 5, 24, 29, 30, and 31, which support arbitrary square sizes.
+
+Under `hp.config`, `clear_cache()` releases cached generation data, and `cache_info()`
+reports its use.
+`cell_limit()` / `set_cell_limit(n)` control the allocation guard. Grid size grows
+exponentially with order; the default limit is a ceiling, not a memory reservation.
+
+More runnable examples are in [examples/](examples/). The curve classification follows
+Estevez-Rams et al., *Hilbert curves in two dimensions*, Rev. Cub. Fís. **34**, 9 (2017).
+The arbitrary-square research is in [research/quasisquares/](research/quasisquares/).
+
+## Try all the features
+
+The [complete runnable example](examples/try_api.py) draws separate figures for the
+curve, data, coarse-grained data, Fourier and difference maps, colour options, fitting
+modes, and a gallery. It also checks numeric round trips, geometry, indexing and groups.
+
+```bash
+python examples/try_api.py
+# Save figures and run all checks without opening windows:
+MPLBACKEND=Agg python examples/try_api.py --save-only
+```
+
+Figures are saved in `examples/output/try_api/`.
+
+## Local API migration
+
+This working-tree redesign replaces the object-based 0.2.0 interface:
+
+| Previous | New |
+| --- | --- |
+| `hilbert_plot(12, data).draw()` | `plot(data, curve=12)` |
+| `curve(12).draw(4)` | `plot_curve(12, order=4)` |
+| `plot.save(path)` | `fig = plot(data); fig.savefig(path)` |
+| `curve(12).points(4)` | `hp.curves.points(12, order=4)` |
+| `curve(12).unroll(img)` | `hp.data.from_grid(img, curve=12)` |
+| `curve(12).name` | `hp.curves.info(12)["name"]` |
+| `proper().names` | `[c["name"] for c in hp.curves.proper()]` |
+
+The old `Curve`, `CurveList`, `HilbertPlot`, and `hilbert_plot` exports are removed.
+`difference=True` now renders the complete difference map. Rendering defaults to
+power-of-two padding. These are intentional interface changes under local review.
+
+## License
+
+MIT © Daniel Estevez — [LICENSE](LICENSE).

hilbertplot-1.0.0/examples/groups.py

@@ -0,0 +1,14 @@
+"""Print the curve groups using ordinary dictionaries: python examples/groups.py."""
+
+import hilbertplot as hp
+
+
+def main():
+    for group in (hp.curves.proper(), hp.curves.improper(), hp.curves.inhomogeneous()):
+        for c in group:
+            print(f"{c['index']:2}  {c['name']:24}  {c['kind']:15}  kernels={c['kernels']}")
+        print()
+
+
+if __name__ == "__main__":
+    main()