fbscatnet 1.0.0__tar.gz

fbscatnet-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # needed for hatch-vcs to see git tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src/
+      - run: pytest -v

fbscatnet-1.0.0/.github/workflows/publish.yaml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'  # Triggers on any tag pushed to GitHub (v0.1, v1.0, v1.3.2, etc.)
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distribution
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # REQUIRED for Trusted Publishing
+      contents: read
+      
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Needed so hatch-vcs gets the version right!
+          
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          
+      - name: Install build tools
+        run: python -m pip install build
+        
+      - name: Build wheel and sdist
+        run: python -m build
+        
+      - name: Publish package
+        # This matches tags with exactly two numbers (e.g., v1.0, v2.1) 
+        # and skips three-part tags (e.g., v1.3.2) or zero-prefixed versions.
+        if: startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '.') && !contains(github.ref, 'v0.')
+        uses: pypa/gh-action-pypi-publish@release/v1

fbscatnet-1.0.0/.github/workflows/sphinx.yaml

@@ -0,0 +1,39 @@
+name: Build and Deploy Sphinx Docs
+
+on:
+  push:
+    branches: [ main ] 
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+            pip install .[docs] 
+
+      - name: Build Sphinx Documentation
+        run: |
+          cd docs
+          sphinx-build -b html . _build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build
+          force_orphan: true

fbscatnet-1.0.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Build artifacts
+build/
+dist/
+*.whl
+
+# Testing / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# Docs build output
+docs/_build/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Features output (from save_embeddings)
+features/
+
+# Models
+models/

fbscatnet-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-tqdm, scipy-stubs, numpy]

fbscatnet-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Released]
+
+## [1.0.0] - 2026-07-31
+### Added
+- Push first production version to PyPI

fbscatnet-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel Venturotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fbscatnet-1.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: fbscatnet
+Version: 1.0.0
+Summary: Fourier-Bessel wavelet scattering transforms
+Project-URL: Homepage, https://github.com/Smee18/FourierBesselWavelets
+Project-URL: Repository, https://github.com/Smee18/FourierBesselWavelets.git
+Project-URL: Issues, https://github.com/Smee18/FourierBesselWavelets/issues
+Author-email: Marcel Venturotti <mv514@bath.ac.uk>
+License: MIT
+License-File: LICENSE
+Keywords: fourier-bessel,image-processing,machine-learning,scattering-transform,wavelets
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: tqdm>=4.65
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scipy-stubs; extra == 'dev'
+Requires-Dist: types-tqdm; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-autobuild; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=11.0; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# fbscatnet
+
+[![PyPI version](https://img.shields.io/pypi/v/fbscatnet.svg)](https://pypi.org/project/fbscatnet/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/fbscatnet.svg)](https://pypi.org/project/fbscatnet/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Smee18/FourierBesselWavelets/actions/workflows/ci.yml/badge.svg)](https://github.com/Smee18/FourierBesselWavelets/actions/workflows/ci.yml)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+`fbscatnet` is a high-performance Python library for computing **Fourier-Bessel wavelet scattering transforms**. It generates robust, feature embeddings from 2D images, making it an ideal feature extractor for computer vision, biomedical imaging, and physics-based machine learning. This is a brand new project of mine that I have been working on for some time. I would love any criticism, improvements, corrections to both the code and the maths.
+
+## Features
+
+- **Novel Wavelet:** New wavelet relying on Bessel basis functions.
+- **Hardware Accelerated:** Seamlessly switch between multi-core CPU execution (`scipy`/`joblib`) and GPU acceleration (`cupy`).
+- **Highly Optimized:** Vectorised filtering in the frequency domain for maximum throughput across large image batches.
+- **ML-Ready:** Outputs flattened feature arrays directly compatible with `scikit-learn`, `xgboost`, or `pytorch`.
+
+## Installation
+
+Install the base package (CPU-only) via pip:
+
+```bash
+pip install fbscatnet
+```
+
+To enable **GPU acceleration**, install with the `gpu` extra (requires a CUDA-compatible GPU):
+
+```bash
+pip install fbscatnet[gpu]
+```
+
+## Quickstart
+
+Extracting features from a dataset takes just a few lines of code:
+
+```python
+import numpy as np
+import logging
+from fbscatnet import FourierBesselWaveletBank, FourierBesselScatNet, logger_config
+logger_config.enable_colored_logs(logging.DEBUG) # IMPORTANT: SET TO SEE LOGS
+
+# 1. Create some dummy image data (e.g., 10 grayscale images of size 64x64)
+images = np.random.rand(10, 64, 64)
+
+# 2. Instantiate a Fourier-Bessel Wavelet Bank
+# size: spatial dimension (64x64), m: angular order, k: radial roots
+bank = FourierBesselWaveletBank(size=64, m=2, k=2, sigma=0.1)
+
+# 3. Initialize the Scattering Network
+# Use backend="gpu" if you installed with CuPy
+net = FourierBesselScatNet(bank=bank, backend="cpu")
+
+# 4. Generate feature embeddings
+# downsize: spatial pooling factor (must evenly divide the image size)
+features = net.generate_embeddings(images, downsize=4, use_multiprocessing=True)
+
+print(f"Generated embeddings shape: {features.shape}")
+# Output: (10, feature_dimension)
+```
+
+## Visualising Wavelet Maps
+
+If you want to inspect how the wavelet filters are interacting with your image at the first scattering order, `fbscatnet` includes a built-in plotting tool:
+
+```python
+# Pass a single 2D image to visualize
+single_image = images[0]
+net.visualise_maps(single_image, downsize=4)
+```
+
+## API Overview
+
+Sphinx documentation at: https://smee18.github.io/FourierBesselWavelets/
+
+The `example` folder also contains a full pipeline, classifying MNIST using the library
+The pdf of my notes taken along this project contains an in-depth explanation of the mathematics behind these wavelets. Here you can find all derivations, proofs and useful information. Some stuff might seem trivial but my goal is to really expose all aspects so anyone new to wavelet theory can understand the mathematics behind these Fourier Bessel wavelets.
+
+## License
+This project is licensed under the MIT License.

fbscatnet-1.0.0/README.md

@@ -0,0 +1,79 @@
+# fbscatnet
+
+[![PyPI version](https://img.shields.io/pypi/v/fbscatnet.svg)](https://pypi.org/project/fbscatnet/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/fbscatnet.svg)](https://pypi.org/project/fbscatnet/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Smee18/FourierBesselWavelets/actions/workflows/ci.yml/badge.svg)](https://github.com/Smee18/FourierBesselWavelets/actions/workflows/ci.yml)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+`fbscatnet` is a high-performance Python library for computing **Fourier-Bessel wavelet scattering transforms**. It generates robust, feature embeddings from 2D images, making it an ideal feature extractor for computer vision, biomedical imaging, and physics-based machine learning. This is a brand new project of mine that I have been working on for some time. I would love any criticism, improvements, corrections to both the code and the maths.
+
+## Features
+
+- **Novel Wavelet:** New wavelet relying on Bessel basis functions.
+- **Hardware Accelerated:** Seamlessly switch between multi-core CPU execution (`scipy`/`joblib`) and GPU acceleration (`cupy`).
+- **Highly Optimized:** Vectorised filtering in the frequency domain for maximum throughput across large image batches.
+- **ML-Ready:** Outputs flattened feature arrays directly compatible with `scikit-learn`, `xgboost`, or `pytorch`.
+
+## Installation
+
+Install the base package (CPU-only) via pip:
+
+```bash
+pip install fbscatnet
+```
+
+To enable **GPU acceleration**, install with the `gpu` extra (requires a CUDA-compatible GPU):
+
+```bash
+pip install fbscatnet[gpu]
+```
+
+## Quickstart
+
+Extracting features from a dataset takes just a few lines of code:
+
+```python
+import numpy as np
+import logging
+from fbscatnet import FourierBesselWaveletBank, FourierBesselScatNet, logger_config
+logger_config.enable_colored_logs(logging.DEBUG) # IMPORTANT: SET TO SEE LOGS
+
+# 1. Create some dummy image data (e.g., 10 grayscale images of size 64x64)
+images = np.random.rand(10, 64, 64)
+
+# 2. Instantiate a Fourier-Bessel Wavelet Bank
+# size: spatial dimension (64x64), m: angular order, k: radial roots
+bank = FourierBesselWaveletBank(size=64, m=2, k=2, sigma=0.1)
+
+# 3. Initialize the Scattering Network
+# Use backend="gpu" if you installed with CuPy
+net = FourierBesselScatNet(bank=bank, backend="cpu")
+
+# 4. Generate feature embeddings
+# downsize: spatial pooling factor (must evenly divide the image size)
+features = net.generate_embeddings(images, downsize=4, use_multiprocessing=True)
+
+print(f"Generated embeddings shape: {features.shape}")
+# Output: (10, feature_dimension)
+```
+
+## Visualising Wavelet Maps
+
+If you want to inspect how the wavelet filters are interacting with your image at the first scattering order, `fbscatnet` includes a built-in plotting tool:
+
+```python
+# Pass a single 2D image to visualize
+single_image = images[0]
+net.visualise_maps(single_image, downsize=4)
+```
+
+## API Overview
+
+Sphinx documentation at: https://smee18.github.io/FourierBesselWavelets/
+
+The `example` folder also contains a full pipeline, classifying MNIST using the library
+The pdf of my notes taken along this project contains an in-depth explanation of the mathematics behind these wavelets. Here you can find all derivations, proofs and useful information. Some stuff might seem trivial but my goal is to really expose all aspects so anyone new to wavelet theory can understand the mathematics behind these Fourier Bessel wavelets.
+
+## License
+This project is licensed under the MIT License.

fbscatnet-1.0.0/docs/conf.py

@@ -0,0 +1,43 @@
+import os
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as get_installed_version
+
+project = "fbscatnet"
+copyright = "2026, Marcel Venturotti"
+author = "Marcel Venturotti"
+try:
+    release = get_installed_version("fbscatnet")
+except PackageNotFoundError:
+    release = "0.0.0"
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",  # Supports Google and NumPy style docstrings
+    "sphinx.ext.viewcode",  # Adds links to highlighted source code
+    "sphinx.ext.intersphinx",  # Links to external documentation (e.g., Python standard library)
+    "sphinx.ext.autosummary",  # Generates stub files for autodoc automatically
+]
+
+# --- Autodoc Customisation ---
+# Controls how members (functions, classes) are ordered in the docs
+autodoc_member_order = "bysource"  # Options: 'alphabetical', 'bysource', 'groupwise'
+
+# Default flags used by all autodoc directives (e.g., show member type hints)
+autodoc_typehints = "description"  # Options: 'signature', 'description', 'none', 'both'
+
+# Automatically mock imports that might not be installed in the readthedocs/build environment
+autodoc_mock_imports = []
+
+# --- Intersphinx Mapping ---
+# Allows linking to Python's built-in types and other libraries
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+html_theme = "sphinx_rtd_theme"
+
+autosummary_generate = True

fbscatnet-1.0.0/docs/index.rst

@@ -0,0 +1,35 @@
+Welcome to fbscatnet's Documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+API Reference
+=============
+
+This section documents the core modules of the ``fbscatnet`` package.
+
+Generate Bank
+-------------
+
+.. automodule:: fbscatnet.generate_bank
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Scatnet
+-------
+
+.. automodule:: fbscatnet.scatnet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`