Catalog, coordinates and geometry¶

hp.curves returns ordinary dictionaries, lists, arrays and scalar values.

hilbertplot.curves.info(which=0)¶

Return plain metadata for a curve selected by index or label.

Parameters:

which (int or str, default 0) – Index 0..39, friendly label such as ‘Moore’, or paper symbol such as ‘12H’. Name matching ignores case, whitespace and ‘#’.

Returns:

info – Keys: index (int), name/symbol/kind (str), homogeneous/closed/generalizes (bool), kernels (sorted list of int), combination (str), and rule (str). kind is ‘proper’, ‘improper’ or ‘inhomogeneous’; generalizes means arbitrary square sizes are supported. Kernels identify building blocks.

Return type:

dict

Raises:

TypeError – Invalid selector type, including bool.
ValueError – Unknown index, label or symbol.

Examples

>>> import hilbertplot as hp
>>> hp.curves.info("Moore")["index"]
1

hilbertplot.curves.catalog()¶

Return metadata for all forty curves, in index order.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.proper()¶

Return metadata for the six proper homogeneous curves.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

Notes

Indices 0-5 assemble four rotated/reflected copies of the lower-order standard Hilbert path (kernel 0). For example, an order-3 Moore path contains four order-2 Hilbert paths, rather than four smaller Moore paths.

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.improper()¶

Return metadata for the six improper homogeneous curves.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

Notes

Indices 6-11 assemble four copies of the lower-order Liu4 path (kernel 5). The rules reverse selected copies to connect their endpoints. Reversal exchanges entry and exit without moving the cells; it is distinct from reflecting the path. These paths remain connected and cover every cell.

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.homogeneous()¶

Return metadata for the twelve homogeneous curves.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

Notes

All four quadrants use the same lower-order kernel type, although its orientation and traversal direction may differ. Indices 0-5 use Hilbert; indices 6-11 use Liu4. Homogeneity describes construction, not data values.

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.inhomogeneous()¶

Return metadata for the twenty-eight inhomogeneous curves.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

Notes

Indices 12-39 mix different lower-order kernel types within one assembly. For example, curve 12 uses Liu2 in the bottom quadrants and Liu4 in the top quadrants. Rotating four copies of a single kernel does not create an inhomogeneous construction.

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.closed()¶

Return metadata for the four curves with adjacent entry and exit cells.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.generalizing()¶

Return metadata for the eight curves supporting arbitrary squares and quasisquares.

Returns:: curves – Metadata in index order, using the same keys as curves.info. Safe to pass directly to gallery; no library-defined objects are returned.
Return type:: list of dict

See also

hilbertplot.curves.info: Metadata keys and curve selection.
hilbertplot.gallery: Render a selection of curves.

hilbertplot.curves.by_kernels(*indices)¶

Select curves with exactly the requested set of quadrant kernels.

Parameters:: *indices (int) – Kernel curve indices. Set matching is exact, not a subset query; order and repetitions do not change the selection.
Returns:: curves – Matching metadata in index order; empty if there is no match.
Return type:: list of dict

See also

hilbertplot.curves.info: Inspect kernels and construction rules.

Examples

>>> import hilbertplot as hp
>>> len(hp.curves.by_kernels(0))
6

hilbertplot.curves.points(curve=0, order=4)¶

Return the ordered cells of a power-of-two curve.

Parameters:

curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.
order (int, default 4) – Nonnegative recursion depth. Side length is 2**order and the path contains 4**order cells. Order zero contains just (0, 0).

Returns:

points – Integer (x, y) coordinates in visit order, normalized to the lower-left origin. Array indexing uses [y, x].

Return type:

numpy.ndarray, shape (4**order, 2)

Raises:

ValueError – Negative order, invalid curve, or allocation over the cell limit.
TypeError – Order is not an integer or is bool.

See also

hilbertplot.curves.index_to_xy: Access a single cell without materializing a path.
hilbertplot.curves.grid: Coordinates for other supported square/quasisquare sizes.

Examples

>>> import hilbertplot as hp
>>> hp.curves.points(0, order=1).tolist()
[[0, 0], [0, 1], [1, 1], [1, 0]]

hilbertplot.curves.grid(n, *, curve=0)¶

Return the ordered cells of a square or quasisquare.

Parameters:

n (int or tuple of int) – Square side, or (rows, columns). Dimensions must be positive; a quasisquare has sides differing by one. General rectangles are rejected.
curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.

Returns:

points – Integer (x, y) coordinates in visit order. Quasisquare orientation is chosen automatically to retain a connected path.

Return type:

numpy.ndarray, shape (rows * columns, 2)

Raises:

ValueError – Unsupported shape/curve combination, nonpositive dimensions, or an allocation over the cell limit.

Notes

Power-of-two squares work on all forty curves. Other sizes require a generalizing curve: 0, 3, 4, 5, 24, 29, 30 or 31. This function returns coordinates, not an image; use data.to_grid to arrange sample values.

Examples

>>> import hilbertplot as hp
>>> hp.curves.grid((15, 16), curve=3).shape
(240, 2)

hilbertplot.curves.word(curve=0, order=4)¶

Return a power-of-two curve as unit direction letters.

Parameters:

curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.
order (int, default 4) – Nonnegative recursion depth.

Returns:

word – String of length 4**order - 1 over ‘u’, ‘d’, ‘l’, ‘r’, for up, down, left and right. The order-zero word is empty.

Return type:

str

Examples

>>> import hilbertplot as hp
>>> hp.curves.word(0, order=1)
'urd'

hilbertplot.curves.index_to_xy(index, order, *, curve=0)¶

Locate one sequence index without building the full curve.

Parameters:

index (int) – Zero-based visit index in [0, 4**order).
order (int) – Nonnegative recursion depth of a power-of-two square.
curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.

Returns:

xy – Cell (x, y), each in [0, 2**order). Python integers retain exactness at very large orders.

Return type:

tuple of int

Raises:

TypeError – A numeric index/order is not an integer, or is bool.
ValueError – Negative order or index outside the curve.

See also

hilbertplot.curves.xy_to_index: Invert this mapping.

Notes

Time and auxiliary space grow with order, not the number of cells. This routine does not allocate a full grid and is independent of the materialized cell limit. Arbitrary square/quasisquare indexing is not supported here.

Examples

>>> import hilbertplot as hp
>>> hp.curves.index_to_xy(2, 1)
(1, 1)

hilbertplot.curves.xy_to_index(x, y, order, *, curve=0)¶

Find the visit index of one cell without building the curve.

Parameters:

x (int) – Cell coordinates in [0, 2**order); x is column and y is row.
y (int) – Cell coordinates in [0, 2**order); x is column and y is row.
order (int) – Nonnegative recursion depth of a power-of-two square.
curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.

Returns:

index – Zero-based visit index in [0, 4**order). Uses exact Python integers.

Return type:

int

Raises:

TypeError – Coordinates/order are not integers, or are bool.
ValueError – Negative order or coordinates outside the grid.

See also

hilbertplot.curves.index_to_xy: Invert this mapping.

Notes

Uses O(order) traversal rather than materializing 4**order cells. Supports power-of-two squares only and is independent of the materialized cell limit.

Examples

>>> import hilbertplot as hp
>>> hp.curves.xy_to_index(1, 1, 1)
2

hilbertplot.curves.label_map(curve=0, order=None, *, side=None)¶

Return the visit index at every square-grid cell.

Parameters:

curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.
order (int or None, optional) – Nonnegative recursion depth. Defaults to 4 if side is also omitted. Mutually exclusive with side.
side (int or None, optional) – Explicit square side. Non-power-of-two sizes require a generalizing curve. Mutually exclusive with order.

Returns:

labels – labels[y, x] is the zero-based visit index of cell (x, y).

Return type:

numpy.ndarray of int64, shape (side, side)

Raises:

ValueError – Both side and order, unsupported side/curve, or excessive allocation.

Notes

Coordinates are (x, y), while array access is [y, x].

Examples

>>> import hilbertplot as hp
>>> hp.curves.label_map(order=1).tolist()
[[0, 3], [1, 2]]

hilbertplot.curves.difference_map(curve=0, order=None, *, side=None)¶

Return mean neighbour visit-index distance at every cell.

Parameters:

curve (int or str, default 0) – Curve index in 0..39, friendly label (for example, “Moore”), or paper symbol (for example, “12H”). The default is the standard Hilbert curve.
order (int or None, optional) – Nonnegative recursion depth. Defaults to 4 if side is also omitted. Mutually exclusive with side.
side (int or None, optional) – Explicit square side. Non-power-of-two sizes require a generalizing curve. Mutually exclusive with order.

Returns:

distances – At each cell, average abs(label_here - label_neighbour) over all in-bounds horizontal, vertical and diagonal neighbours. Corners have three neighbours, edges five, interiors eight. A single cell gives 0.

Return type:

numpy.ndarray of float64, shape (side, side)

Raises:

ValueError – Both side and order, unsupported side/curve, or excessive allocation.

Notes

This describes geometry, independently of measurement values. Large values mean spatial neighbours can be far apart along the sequence. To match a plot’s grid, pass side=hp.data.to_grid(values, curve=…).shape[0].

Examples

>>> import hilbertplot as hp
>>> hp.curves.difference_map(order=0).tolist()
[[0.0]]

hilbertplot.curves.is_space_filling(points, side, *, connected=True)¶

Check coverage and optional connectivity of a discrete square-grid path.

Parameters:

points (array_like, shape (N, 2)) – Integer (x, y) cells in visit order. A valid square path has N=side**2.
side (int) – Positive square side length, not a recursion order.
connected (bool, default True) – Also require unit horizontal/vertical steps between successive cells. False checks coverage, uniqueness and bounds only.

Returns:

valid – Whether the path visits every cell of the given square once, with connectivity when requested. General rectangles are not checked.

Return type:

bool

See also

hilbertplot.curves.points: Generate a power-of-two path.
hilbertplot.curves.grid: Generate other supported path sizes.

Examples

>>> import hilbertplot as hp
>>> hp.curves.is_space_filling(hp.curves.points(0, order=3), side=8)
True
>>> hp.curves.is_space_filling(hp.curves.points(0, order=3), side=16)
False

hilbertplot.curves.canonical_form(points)¶

Build a byte key invariant to square symmetries and traversal reversal.

Parameters:: points (numpy.ndarray, shape (N, 2)) – Nonempty integer (x, y) coordinates. Compare arrays with compatible dtype and byte order; the key uses their native byte representation.
Returns:: key – Lexicographically smallest translated path representation among eight square symmetries and both traversal directions.
Return type:: bytes

See also

hilbertplot.curves.is_space_filling: Check square coverage and connectivity.

Notes

Coordinates are shifted so their minimum is (0, 0). Equal keys identify paths related by these operations when dtype/representation agree. The key is not a portable serialization or a validation of space filling.

Examples

>>> import hilbertplot as hp
>>> points = hp.curves.points(0, order=3)
>>> hp.curves.canonical_form(points) == hp.curves.canonical_form(points[::-1])
True