Array conversion and transforms¶

Functions in hp.data return numeric arrays without drawing figures. Conversion rearranges numeric values; explicit granularity or Fourier transforms change them.

hilbertplot.data.to_grid(data, *, curve=0, shape=None, granularity=1, fit='pad', order=None, fill=nan)¶

Arrange numeric samples into a grid along a curve, preserving dtype.

Parameters:

data (array_like, shape (N, ...) or (N,)) – Nonempty numeric samples, including boolean, integer, float and complex arrays. Trailing sample axes are retained as pixel component axes. A flat color sequence can be reconstructed using its full original shape.
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.
shape (tuple of int or None, optional) – Explicit (rows, columns), optionally followed by channel dimensions. Spatial dimensions must form a supported square or quasisquare (sides differing by one). Mutually exclusive with order.
granularity (int, default 1) – Positive block length. Replace consecutive blocks with their means, repeated to preserve sequence length. A final short block uses its own mean. One leaves samples unchanged; averaging is lossy.
fit ({'pad', 'square', 'truncate', 'auto'}, default 'pad') – ‘pad’ uses the smallest enclosing power-of-two square. ‘square’ uses a side of ceil(sqrt(N)) and requires a generalizing curve. ‘truncate’ uses the largest power-of-two square fitting inside the sequence and discards the tail. ‘auto’ chooses ‘square’ when supported, else ‘pad’.
order (int or None, optional) – Fix the grid side to 2**order, with order >= 0. Without an explicit order, use fit to determine the size. Too much data raises unless fit=’truncate’.
fill (numeric scalar, default numpy.nan) – Padding value. Default NaN padding preserves floating/complex dtype; integer/bool inputs use masked padding to preserve exact values. An explicit representable fill, such as 0, retains an ordinary integer array. An unrepresentable fill raises when padding is required.

Returns:

grid – Shape (rows, columns, …) with sample i at grid[y_i, x_i, …]. Input masks are preserved. With granularity=1 the input dtype is retained exactly, including large integers and complex values.

Return type:

numpy.ndarray or numpy.ma.MaskedArray

Raises:

TypeError – Non-numeric data, non-integer dimensions, or a nonscalar fill.
ValueError – Empty/scalar data, unsupported shape, incompatible channel axes, both shape and order, unrepresentable padding, or insufficient capacity.

See also

hilbertplot.data.from_grid: Read values along a curve.
hilbertplot.plot: Display real scalar samples.

Notes

Square/quasisquare paths agree with plot_curve(shape=…). General rectangles are unsupported. Conversion performs no color normalization. Padding is retained by from_grid; pass the known original length to remove only the tail. Averaging and explicit truncation prevent an exact round trip.

Examples

>>> import numpy as np
>>> import hilbertplot as hp
>>> values = np.arange(10, dtype=np.uint64)
>>> grid = hp.data.to_grid(values, curve=12)
>>> hp.data.from_grid(grid, curve=12, length=10).tolist()
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

hilbertplot.data.from_grid(array, *, curve=0, length=None)¶

Read a grid along a curve into one flat sequence.

Parameters:

array (array_like, shape (rows, columns, ...)) – At least two spatial dimensions, forming a supported square or quasisquare. Optional trailing axes contain pixel components.
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.
length (int or None, optional) – Retain exactly this many flattened values, from 0 through array.size. Counts channels as individual values. None keeps every value, including NaNs, masks and padding; nothing is stripped automatically.

Returns:

sequence – Values in curve visit order, with each pixel’s components consecutive. Dtype and masks are preserved. M is array.size unless length is given.

Return type:

numpy.ndarray or numpy.ma.MaskedArray, shape (M,)

Raises:

TypeError – Non-integer length or dimensions.
ValueError – Fewer than two dimensions, empty component axes, unsupported spatial shape, or length outside the available range.

See also

hilbertplot.data.to_grid: Inverse arrangement using the same curve and shape.

Notes

Reconstruct with to_grid(sequence, curve=the_same_curve, shape=array.shape). Reading with another curve reorders values and may move padding into the middle of the sequence. Keep every entry to invert such a permutation.

Examples

>>> import numpy as np
>>> import hilbertplot as hp
>>> image = np.arange(16).reshape(4, 4)
>>> sequence = hp.data.from_grid(image, curve=12)
>>> np.array_equal(hp.data.to_grid(sequence, curve=12, shape=image.shape), image)
True

hilbertplot.data.granulate(data, granularity)¶

Replace each consecutive block by repeated copies of its arithmetic mean.

Parameters:

data (array_like) – Real numeric input, flattened to one dimension and converted to float64. Non-finite values propagate through their block means; no values are omitted automatically. Use data.to_grid for mask-aware conversion.
granularity (int) – Positive block length. One returns a float64 copy of the flattened input. A final short block is averaged over its available values.

Returns:

coarse – Same number of values, with one mean repeated across each block.

Return type:

numpy.ndarray of float64, shape (data.size,)

Raises:

TypeError – Block length is not an integer or is bool.
ValueError – Block length is less than one.

See also

hilbertplot.plot: Use granularity to coarsen while plotting.

Notes

This is not decimation: sequence length stays fixed. Averaging is lossy and happens in sequence order before mapping to pixels. For a block B, every output position in B receives sum(data[B]) / len(B). The standalone helper converts via numpy.asarray; masked arrays should be handled with explicit missing-value policy or the mask-aware to_grid pipeline.

Examples

>>> import hilbertplot as hp
>>> hp.data.granulate([0, 2, 10, 14, 7], 2).tolist()
[1.0, 1.0, 12.0, 12.0, 7.0]

hilbertplot.data.fourier(data, *, curve=0, granularity=1, fit='pad', order=None, log=True, window=False, remove_dc=True)¶

Compute the centred 2-D FFT magnitude of a mapped sequence.

Parameters:

data (array_like, shape (N,)) – Nonempty real numeric sequence. NaNs and masked samples denote missing values. Infinities and complex inputs 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.
granularity (int, default 1) – Positive block length. Replace consecutive blocks with their means, repeated to preserve sequence length. A final short block uses its own mean. One leaves samples unchanged; averaging is lossy.
fit ({'pad', 'square', 'truncate', 'auto'}, default 'pad') – ‘pad’ uses the smallest enclosing power-of-two square. ‘square’ uses a side of ceil(sqrt(N)) and requires a generalizing curve. ‘truncate’ uses the largest power-of-two square fitting inside the sequence and discards the tail. ‘auto’ chooses ‘square’ when supported, else ‘pad’.
order (int or None, optional) – Fix the grid side to 2**order, with order >= 0. Without an explicit order, use fit to determine the size. Too much data raises unless fit=’truncate’.
log (bool, default True) – Return log1p(abs(F)) instead of abs(F).
window (bool, default False) – Multiply the mapped image by separable Hann weights before the FFT. This tapers edges; it is not a moving window on the sequence.
remove_dc (bool, default True) – Subtract the image mean before optional windowing and transformation.

Returns:

spectrum – Real nonnegative FFT magnitude, with zero frequency at the centre. This is not squared power, a normalized density, or a 1-D FFT.

Return type:

numpy.ndarray, shape (side, side)

Raises:

ValueError – No finite samples, invalid fitting, incompatible size, or infinity.

See also

hilbertplot.plot: Pass fourier=True to render the spectrum.

Notes

First map the data and replace missing cells by the finite image mean. Optionally subtract the mean, then multiply by outer(numpy.hanning(rows), numpy.hanning(columns)) when window=True. Compute abs(fftshift(fft2(image))) and optionally apply log1p. The Hann window changes sample weights and amplitudes; there is no gain correction. At sides 1 or 2 its special/degenerate weights matter.

Examples

>>> import hilbertplot as hp
>>> hp.data.fourier(range(100), curve=12).shape
(16, 16)