hilbertplot 0.2.0__tar.gz → 1.0.1__tar.gz

{hilbertplot-0.2.0 → hilbertplot-1.0.1}/CHANGELOG.md

@@ -7,6 +7,42 @@ All notable changes to **hilbertplot** are documented here. The format follows
 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
@@ -27,6 +63,34 @@ validates `fit` instead of ignoring it.
 
 <!-- version list -->
 
+## v1.0.1 (2026-11-01)
+
+### Bug Fixes
+
+- Provide citation metadata for software archives
+  ([`be2d92b`](https://github.com/El3ssar/hilbertplot/commit/be2d92b00b5d8ce083eec3c6c9ec5a2d9215028c))
+
+### Testing
+
+- Measure construction allocations without interpreter overhead
+  ([`0b95704`](https://github.com/El3ssar/hilbertplot/commit/0b9570438681c47d0736415c1e74fb8522d2f04e))
+
+
+## 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

hilbertplot-1.0.1/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: hilbertplot
+Version: 1.0.1
+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.1/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.1/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()

{hilbertplot-0.2.0 → hilbertplot-1.0.1}/examples/plot_catalog.py

@@ -7,6 +7,11 @@ Writes to examples/output/.
 
 import os
 
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
 import hilbertplot as hp
 
 OUT = os.path.join(os.path.dirname(__file__), "output")
@@ -14,28 +19,33 @@ os.makedirs(OUT, exist_ok=True)
 
 
 def main() -> None:
-    hp.gallery(
-        hp.homogeneous(),
+    fig = hp.gallery(
+        hp.curves.homogeneous(),
         order=4,
         ncols=6,
         title="The 12 homogeneous Hilbert curves (order 4)",
-        save=os.path.join(OUT, "homogeneous.png"),
     )
-    hp.gallery(
-        hp.inhomogeneous(),
+    fig.savefig(os.path.join(OUT, "homogeneous.png"), dpi=140)
+    plt.close(fig)
+    fig = hp.gallery(
+        hp.curves.inhomogeneous(),
         order=3,
         ncols=7,
         title="The 28 inhomogeneous Hilbert curves (order 3)",
-        save=os.path.join(OUT, "inhomogeneous.png"),
     )
-    hp.gallery(
-        hp.catalog(),
+    fig.savefig(os.path.join(OUT, "inhomogeneous.png"), dpi=140)
+    plt.close(fig)
+    fig = hp.gallery(
+        hp.curves.catalog(),
         order=3,
         ncols=8,
         title="All 40 two-dimensional Hilbert curves (order 3)",
-        save=os.path.join(OUT, "all40.png"),
     )
-    hp.curve(0).save(os.path.join(OUT, "hilbert_order6.png"), 6)
+    fig.savefig(os.path.join(OUT, "all40.png"), dpi=140)
+    plt.close(fig)
+    fig = hp.plot_curve(0, order=6)
+    fig.savefig(os.path.join(OUT, "hilbert_order6.png"), dpi=140)
+    plt.close(fig)
     print(f"wrote plots to {OUT}")
 
 

hilbertplot-1.0.1/examples/plot_data.py

@@ -0,0 +1,34 @@
+"""One call, one plot: python examples/plot_data.py. Writes examples/output/."""
+
+from pathlib import Path
+
+import matplotlib
+import numpy as np
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+import hilbertplot as hp
+
+
+def main():
+    out = Path(__file__).parent / "output"
+    out.mkdir(exist_ok=True)
+    t = np.arange(1000)
+    data = np.sin(2 * np.pi * t / 97) + 0.4 * np.cos(2 * np.pi * t / 31)
+    for name, options in (
+        ("data", {}),
+        ("granularity", {"granularity": 16}),
+        ("fourier", {"fourier": True, "window": True}),
+        ("difference", {"difference": True}),
+    ):
+        fig = hp.plot(data, curve=12, **options)
+        fig.savefig(out / f"{name}.png", dpi=160)
+        plt.close(fig)
+    fig = hp.plot(data, curve="Moore", cmap=["navy", "white", "firebrick"])
+    fig.savefig(out / "colours.png", dpi=160)
+    plt.close(fig)
+
+
+if __name__ == "__main__":
+    main()