Metadata-Version: 2.4
Name: filterbanks
Version: 0.0.1
Summary: Filter Banks and Multiresolution Transform Layers
Project-URL: Homepage, https://github.com/kkt-ee/filterbanks
Project-URL: Issues, https://github.com/kkt-ee/filterbanks/issues
Author-email: Kishore Kumar Tarafdar <kkt.ee.ai@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: numpy
Requires-Dist: tensorflow>=2.15
Provides-Extra: exact-dwt
Requires-Dist: tfdwt>=0.0.1; extra == 'exact-dwt'
Provides-Extra: plot
Requires-Dist: matplotlib; extra == 'plot'
Provides-Extra: shearlet
Requires-Dist: tfdst>=0.0.1; extra == 'shearlet'
Description-Content-Type: text/markdown

# filterbanks: Filter Banks and Multiresolution Transform Layers

`filterbanks` provides TensorFlow/Keras layers for multiresolution and geometric filter banks.

[![PyPI Version](https://img.shields.io/pypi/v/filterbanks?label=PyPI&color=gold)](https://pypi.org/project/filterbanks/)
[![Python Versions](https://img.shields.io/pypi/pyversions/filterbanks)](https://pypi.org/project/filterbanks/)
[![TensorFlow Version](https://img.shields.io/badge/tensorflow-2.15%2B-darkorange)](https://www.tensorflow.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-deepgreen.svg?style=flat)](https://github.com/kkt-ee/filterbanks/LICENSE)

## Capabilities

- `DCT2D` / `IDCT2D`
- `MultiLevelLiftingDWT1D_K`
- `MultiLevelLiftingDWT2D_K`
- `MultiLevelLiftingDWT3D_K`
- `LapPyrAnalysis` / `LapPyrSynthesis`
- `MonogenicPyramid2D`
- `SteerablePyramid2D`
- `Scattering2D`
- `WaveAtoms2DAnalysis` / `WaveAtoms2DSynthesis`
- `WignerVille1D`
- `filterbanks.tileviewer` for tiling plots

## Limitations

- Some layers are analysis-only and do not include a synthesis inverse.
- Exact perfect reconstruction applies only to paired forward/inverse classes where provided.
- Optional viewer and probe utilities may require extra packages such as `matplotlib`.

## Installation

```bash
pip install filterbanks
```

## Transform References

| Transform | Class / Layer | Original paper |
|---|---|---|
| DCT | `DCT2D`, `IDCT2D` | Ahmed, Natarajan, Rao, [Discrete Cosine Transform](https://doi.org/10.1109/T-C.1974.223784), IEEE Trans. Computers, 1974 |
| Monogenic Pyramid | `MonogenicPyramid2D` | Felsberg, Sommer, [The monogenic signal](https://doi.org/10.1109/78.969520), IEEE Trans. Signal Processing, 2001 |
| Laplacian Pyramid | `LapPyrAnalysis`, `LapPyrSynthesis` | Burt, Adelson, [The Laplacian Pyramid as a Compact Image Code](https://doi.org/10.1109/TCOM.1983.1095851), IEEE Trans. Communications, 1983 |
| DWT / Wavelets | `MultiLevelLiftingDWT1D_K`, `MultiLevelLiftingDWT2D_K`, `MultiLevelLiftingDWT3D_K` | Daubechies, [Orthonormal bases of compactly supported wavelets](https://doi.org/10.1002/cpa.3160410705), Comm. Pure Appl. Math., 1988 |
| Lifting DWT | `MultiLevelLiftingDWT1D_K`, `MultiLevelLiftingDWT2D_K`, `MultiLevelLiftingDWT3D_K` | Sweldens, [The lifting scheme: A construction of second generation wavelets](https://doi.org/10.1137/S0036141095289051), SIAM J. Math. Anal., 1998 |
| Steerable Pyramid | `SteerablePyramid2D` | Freeman, Adelson, [The design and use of steerable filters](https://doi.org/10.1109/34.93808), IEEE TPAMI, 1991 |
| Curvelet | `CurveletTransform2D` | Candès, Donoho, [New tight frames of curvelets and optimal representations of objects with piecewise C2 singularities](https://doi.org/10.1002/cpa.10116), Comm. Pure Appl. Math., 2004 |
| Contourlet | `ContourletTransform2D` | Do, Vetterli, [The contourlet transform: an efficient directional multiresolution image representation](https://doi.org/10.1109/TIP.2005.859376), IEEE Trans. Image Processing, 2005 |
| Wave Atoms | `WaveAtoms2DAnalysis`, `WaveAtoms2DSynthesis` | Demanet, Ying, [Wave atoms and sparsity of oscillatory patterns](https://doi.org/10.1016/j.acha.2007.03.003), Appl. Comput. Harmon. Anal., 2007 |
| Shearlet | `ShearletAnalysis2D`, `ShearletSynthesis2D` | Kutyniok, Labate, [Resolution of the wavefront set using continuous shearlets](https://doi.org/10.1090/S0002-9947-08-04700-4), Trans. Amer. Math. Soc., 2009 |
| Scattering | `Scattering2D` | Mallat, [Group invariant scattering](https://doi.org/10.1002/cpa.21413), Comm. Pure Appl. Math., 2012 |
| Wigner-Ville | `WignerVille1D` | Wigner, [On the Quantum Correction for Thermodynamic Equilibrium](https://doi.org/10.1103/PhysRev.40.749), 1932; Ville, [Application de la notion de signal analytique a la determination de l'amplitude et de la frequence instantanee d'un signal](https://doi.org/10.1007/BF02997542), 1948 |

## Package-Specific Layers

| Layer | Note |
|---|---|
| `DWT2DPR` | Exact 2D filter-bank operator form used for validation |
| `ShearletPRFBLifting` | Trainable shearlet PRFB layers implemented in this package |
| `DirectionalLiftingNSDL` | Trainable nonsubsampled directional lifting layers implemented in this package |

## Minimal Example

```python
import tensorflow as tf
from filterbanks import MultiLevelLiftingDWT2D_K

x = tf.random.normal([1, 64, 64, 1])
layer = MultiLevelLiftingDWT2D_K(levels=2, preset="haar")

pyr = layer(x)
y = layer.synth(*pyr)

print(x.shape, y.shape)
```

## Tiling Viewer

```bash
python -m filterbanks.tileviewer.main_viewer --transform contourlet --levels 3 --Ks 4 8 8 --kappas 64 64 64 --H 256 --W 256 --save Figs/contourlet_tiling.png
```

## Citation

This software is released for broad research, educational, and engineering use. If this package helps your work, please cite the following paper:

```bibtex
@misc{tarafdar2026interpretablefrugallearningsystems,
      title={Interpretable and Frugal Learning Systems Employing Multiresolution Pyramids and Volterra Kernels},
      author={Kishore Kumar Tarafdar},
      year={2026},
      eprint={2606.15011},
      archivePrefix={arXiv},
      primaryClass={eess.SP},
      url={https://arxiv.org/abs/2606.15011},
}
```

## License

Apache License 2.0. See [`LICENSE`](LICENSE).
