Decompose#

The splineops.decompose package provides functionality for pyramid decomposition (downsampling/up-sampling) and wavelet transforms (analysis and synthesis) based on spline models.

Pyramid Module#

The splineops.decompose.pyramid module implements 1D and 2D REDUCE/EXPAND operations with mirror boundary handling. These form the foundation for many wavelet constructions.

Key functionalities:

get_pyramid_filter Retrieve filter coefficients (g for REDUCE, h for EXPAND) plus a “centered” flag.
reduce_1d, expand_1d Down/upsample a 1D signal using the specified filters and mirror reflection.
reduce_2d, expand_2d Down/upsample a 2D image row-by-row and column-by-column.

Example (pyramid usage)#

from splineops.decompose.pyramid import get_pyramid_filter, reduce_1d, expand_1d
import numpy as np

# Retrieve filter for a spline of order 3
g, h, centered = get_pyramid_filter("Spline", 3)

# 1D reduce/expand
x = np.array([0,1,2,3,2,1,0,-2,-4,-6], dtype=float)
x_reduced = reduce_1d(x, g, centered)
x_expanded = expand_1d(x_reduced, h, centered)

print("Original:", x)
print("Reduced: ", x_reduced)
print("Expanded:", x_expanded)

# 2D reduce/expand
arr = np.random.rand(8,8).astype(np.float32)
arr_reduced = reduce_2d(arr, g, centered)
arr_expanded = expand_2d(arr_reduced, h, centered)

API Reference: Pyramid#

pyramid.py#

Implements pyramid decomposition (reduce & expand) in 1D and 2D using filters derived from spline expansions. Boundary handling is done via mirror reflection, closely mimicking original C routines:

“ReduceStandard_1D” / “ExpandStandard_1D”
“ReduceCentered_1D” / “ExpandCentered_1D”

Usage Example#

from splineops.decompose.pyramid import (
    get_pyramid_filter,
    reduce_1d, expand_1d,
    reduce_2d, expand_2d
)
import numpy as np

# Retrieve filter
g, h, is_centered = get_pyramid_filter("Spline", 3)

# 1D reduce/expand
x = np.array([0, 1, 2, 3, 2, 1, 0, -2, -4, -6], dtype=float)
x_reduced = reduce_1d(x, g, is_centered)
x_expanded = expand_1d(x_reduced, h, is_centered)

# 2D reduce/expand
arr = np.random.rand(8, 8).astype(np.float32)
arr_reduced = reduce_2d(arr, g, is_centered)
arr_expanded = expand_2d(arr_reduced, h, is_centered)

splineops.decompose.pyramid.get_pyramid_filter(name: str, order: int)#

Retrieve the reduce/expand filters for a particular spline family and order.

Parameters:

name (str) – Filter family name, e.g. “Spline”, “Centered Spline”.
order (int) – Spline order (e.g. 3).

Returns:

g (np.ndarray) – 1D filter for REDUCE operation.
h (np.ndarray) – 1D filter for EXPAND operation.
is_centered (bool) – True if the filter is a centered variant; False otherwise.

Raises:

ValueError – If the combination of name/order is not implemented.

splineops.decompose.pyramid.wrap_reflect(i: int, n: int) → int#

Mirror boundary reflection of index i into the range [0..n-1].

If n >= 2, uses period = 2*(n-1). If n < 2, everything maps to 0.

Parameters:

i (int) – Original index (may be out of bounds).
n (int) – Length of the signal.

Returns:

Reflected index within [0..n-1].

Return type:

int

splineops.decompose.pyramid.reduce_1d(signal: ndarray, g: ndarray, centered: bool) → ndarray#

Reduce a 1D signal by factor of 2 using filter g.

Parameters:

signal (np.ndarray) – Input 1D signal of length >= 2.
g (np.ndarray) – Filter for reduction (REDUCE).
centered (bool) – Indicates if the filter is a centered variant.

Returns:

Reduced signal of length roughly n/2.

Return type:

np.ndarray

splineops.decompose.pyramid.expand_1d(signal: ndarray, h: ndarray, centered: bool) → ndarray#

Expand a 1D signal by factor of 2 using filter h.

Parameters:

signal (np.ndarray) – Input 1D signal (coarse scale).
h (np.ndarray) – Filter for expansion (EXPAND).
centered (bool) – Indicates if the filter is a centered variant.

Returns:

Expanded signal of length ~ 2*n.

Return type:

np.ndarray

splineops.decompose.pyramid.reduce_2d(image: ndarray, g: ndarray, centered: bool) → ndarray#

Reduce a 2D image by factor of 2 in each dimension.

Parameters:

image (np.ndarray) – Input 2D array (ny, nx).
g (np.ndarray) – 1D reduce filter.
centered (bool) – True if using centered reduce logic.

Returns:

Reduced image of shape (ny//2, nx//2) if ny,nx >= 2, else smaller.

Return type:

np.ndarray

splineops.decompose.pyramid.expand_2d(image: ndarray, h: ndarray, centered: bool) → ndarray#

Expand a 2D image by factor of 2 in each dimension.

Parameters:

image (np.ndarray) – Input 2D array (coarse scale).
h (np.ndarray) – 1D expand filter.
centered (bool) – True if using centered expand logic.

Returns:

Expanded image, roughly 2*ny by 2*nx.

Return type:

np.ndarray

Wavelet Modules#

The splineops.decompose.wavelets subpackage provides various wavelet transforms (Haar, spline-based) using row-column (or column-row) passes. Classes typically define:

analysis (multi-scale forward transform)
synthesis (multi-scale inverse transform)

Submodules:

splineops.decompose.wavelets.abstractwavelets – Base AbstractWavelets class
splineops.decompose.wavelets.haar – Pure 2D Haar wavelets (HaarWavelets)
splineops.decompose.wavelets.splinewavelets – Spline wavelets, e.g. Spline1Wavelets, Spline3Wavelets, etc.
splineops.decompose.wavelets.splinewaveletstool – Low-level “splitMirror” & “mergeMirror” routines, plus SplineWaveletsTool class

API Reference: Wavelets#

abstractwavelets.py#

Defines a base class for wavelet analysis & synthesis on 2D (or 3D) signals.

class splineops.decompose.wavelets.abstractwavelets.AbstractWavelets(scales=3)#

Bases: object

Base class for wavelet decomposition with multi-scale analysis & synthesis.

Subclasses must override:

analysis1() (single-scale wavelet decomposition)
synthesis1() (single-scale wavelet reconstruction)

Parameters:: scales (int) – Number of scales for multi-scale decomposition.

scales#

Number of scales for repeated analysis/synthesis steps.

Type:: int

analysis(inp: ndarray) → ndarray#

Multi-scale wavelet analysis in 2D (or 3D). Repeatedly calls analysis1() from fine to coarse.

Parameters:: inp (np.ndarray) – Input array with shape (ny, nx) or (nz, ny, nx).
Returns:: Full wavelet decomposition (in-place layout).
Return type:: np.ndarray

analysis1(inp: ndarray) → ndarray#

Single-scale wavelet transform of inp -> out. Must be overridden.

Parameters:: inp (np.ndarray) – Input array (2D or 3D typically).
Returns:: Transformed array (same shape).
Return type:: np.ndarray

get_documentation() → str#: Returns a short description of the wavelet.

get_name() → str#: Returns a descriptive name for the wavelet transform.

set_scale(scale: int)#

Update the number of scales.

Parameters:: scale (int) – New scale value.

synthesis(inp: ndarray) → ndarray#

Multi-scale wavelet synthesis in 2D (or 3D). Repeatedly calls synthesis1() from coarsest to finest.

Parameters:: inp (np.ndarray) – Wavelet decomposition array (same shape as original).
Returns:: Reconstructed array (same shape as input).
Return type:: np.ndarray

synthesis1(inp: ndarray) → ndarray#

Single-scale inverse wavelet transform of inp -> out. Must be overridden.

Parameters:: inp (np.ndarray) – Input wavelet coefficients (single scale).
Returns:: Reconstructed array at that scale.
Return type:: np.ndarray

haar.py#

Implements a 2D Haar wavelet transform via row->column decomposition (analysis) and column->row synthesis. Requires ny >= 2 and nx >= 2.

class splineops.decompose.wavelets.haar.HaarWavelets(scales=3)#

Bases: AbstractWavelets

A 2D Haar wavelet transform for images with shape (ny, nx).

Parameters:: scales (int) – Number of scales (defaults to 3).

q#

Normalization factor, sqrt(2).

Type:: float

Raises:: ValueError – If ny < 2 or nx < 2 at any scale.

Notes

Single-scale steps:

row-wise split
column-wise split

Synthesis:

column-wise merge
row-wise merge

analysis1(inp: ndarray) → ndarray#

Single-scale 2D Haar analysis (row-split, then col-split).

Parameters:: inp (np.ndarray) – 2D array with shape (ny, nx), both >= 2.
Returns:: Transformed array (same shape).
Return type:: np.ndarray

get_documentation()#: Return short docstring for Haar wavelets.

get_name()#: Return ‘Haar2D’.

synthesis1(inp: ndarray) → ndarray#

Single-scale 2D Haar synthesis (inverse of analysis1).

Parameters:: inp (np.ndarray) – 2D array (ny, nx), both >= 2.
Returns:: Reconstructed array.
Return type:: np.ndarray

splinewavelets.py#

Implements Spline wavelet transforms of orders 1, 3, 5.

class splineops.decompose.wavelets.splinewavelets.Spline1Wavelets(scales=3)#

Bases: SplineWavelets

Spline Wavelets of order=1.

get_documentation()#: Return a short docstring describing the spline wavelet order.

get_name()#: Return ‘Spline{order}’.

class splineops.decompose.wavelets.splinewavelets.Spline3Wavelets(scales=3)#

Bases: SplineWavelets

Spline Wavelets of order=3.

get_documentation()#: Return a short docstring describing the spline wavelet order.

get_name()#: Return ‘Spline{order}’.

class splineops.decompose.wavelets.splinewavelets.Spline5Wavelets(scales=3)#

Bases: SplineWavelets

Spline Wavelets of order=5.

get_documentation()#: Return a short docstring describing the spline wavelet order.

get_name()#: Return ‘Spline{order}’.

class splineops.decompose.wavelets.splinewavelets.SplineWavelets(scales=3, order=3)#

Bases: AbstractWavelets

A generic spline wavelet class that references a given ‘order’ (1,3,5). Uses row->column passes with mirror boundary to compute detail.

Parameters:

scales (int) – Number of scales.
order (int) – Spline order (1,3,5).

filter#

Holds the arrays h[] (lowpass) and g[] (highpass).

Type:: SplineFilter

analysis1(inp: ndarray) → ndarray#

Single-scale 2D spline wavelet analysis pass: - Row pass (splitMirror) - Column pass (splitMirror)

Parameters:: inp (np.ndarray) – 2D array.
Returns:: Transformed 2D array (same shape).
Return type:: np.ndarray

get_documentation()#: Return a short docstring describing the spline wavelet order.

get_name()#: Return ‘Spline{order}’.

synthesis1(inp: ndarray) → ndarray#

Single-scale 2D spline wavelet synthesis pass: - Column pass (mergeMirror) - Row pass (mergeMirror)

Parameters:: inp (np.ndarray) – 2D array of wavelet coefficients (one scale).
Returns:: Reconstructed array (same shape).
Return type:: np.ndarray

splinewaveletstool.py#

Uses a SplineFilter to get h[] and g[], then does ‘splitMirror’ and ‘mergeMirror’ passes on rows, then columns.

class splineops.decompose.wavelets.splinewaveletstool.SplineWaveletsTool(scale: int, order: int)#

Bases: object

Equivalent of SplineWaveletsTool.java for 2D analysis/synthesis.

Parameters:

scale (int) – Number of scales (used externally, if needed).
order (int) – Spline order, e.g. 3.

filters#

Holds arrays h (lowpass) and g (highpass).

Type:: SplineFilter

analysis1(inp)#: Single-scale 2D analysis (row pass then column pass).

synthesis1(inp)#: Single-scale 2D synthesis (inverse).

splineops.decompose.wavelets.splinewaveletstool.merge_mirror_1d(vin: ndarray, h: ndarray, g: ndarray) → ndarray#

Inverse of split_mirror_1d. Recombines lowpass and highpass into original signal.

Parameters:

vin (np.ndarray) – 1D array, half is lowpass, half is highpass.
h (np.ndarray) – Lowpass filter.
g (np.ndarray) – Highpass filter.

Returns:

1D reconstructed array.

Return type:

np.ndarray

splineops.decompose.wavelets.splinewaveletstool.split_mirror_1d(vin: ndarray, h: ndarray, g: ndarray) → ndarray#

1D mirror-based ‘split’ producing lowpass + highpass sub-bands.

Parameters:

vin (np.ndarray) – 1D input array.
h (np.ndarray) – Lowpass filter coefficients.
g (np.ndarray) – Highpass filter coefficients.

Returns:

1D array same length as vin, first half = lowpass, second half = detail.

Return type:

np.ndarray

Decompose#

Pyramid Module#

Example (pyramid usage)#

API Reference: Pyramid#

pyramid.py#

Usage Example#

Wavelet Modules#

API Reference: Wavelets#

abstractwavelets.py#

haar.py#

splinewavelets.py#

splinewaveletstool.py#

This Page