add docs and deploy as torch-fourier-shift

.copier-answers.yml

@@ -5,7 +5,7 @@ author_email: [email protected]
 author_name: Alister Burt
 github_username: alisterburt
 mode: tooling
-module_name: torch_phase_shift
+module_name: torch_fourier_shift
 project_name: torch-phase-shift
 project_short_description: Translate images by phase shifting Fourier transforms in
     PyTorch

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+# This job installs dependencies, builds the book, and pushes it to
+# the `gh-pages` branch of the same repository.
+jobs:
+  deploy-book:
+    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.10"
+
+      - name: Install dependencies
+        run: |
+          pip install -e .[docs]
+
+      # Build the book
+      - name: Build the book
+        run: |
+          mkdocs build
+
+      # Push the site to github-pages
+      - name: GitHub Pages action
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_dir: ./site
+          github_token: ${{ secrets.GITHUB_TOKEN }}

docs/examples/shift_dft_2d.md

@@ -0,0 +1 @@
+::: torch_fourier_shift.fourier_shift_dft_2d

docs/examples/shift_dft_3d.md

@@ -0,0 +1 @@
+::: torch_fourier_shift.fourier_shift_dft_3d

docs/examples/shift_image_2d.md

@@ -0,0 +1,24 @@
+```python
+import torch
+from torch_fourier_shift import fourier_shift_image_2d
+
+# create a dummy image
+my_image = torch.tensor(
+    [[0, 0, 0, 0, 0, 0],
+     [0, 1, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0]]
+)
+
+# shift the image by 1 pixel in dim 0, 2 pixels in dim 1
+shifted_image = fourier_shift_image_2d(image=my_image, shifts=torch.tensor([1, 2]))
+```
+
+## Notes
+- shifts can be applied to arrays of 2D images `(..., h, w)`
+- arrays of 2D shifts are supported `(..., 2)`
+
+::: torch_fourier_shift.fourier_shift_image_2d
+

docs/examples/shift_image_3d.md

@@ -0,0 +1,23 @@
+```python
+import torch
+from torch_fourier_shift import fourier_shift_image_2d
+
+# create a dummy image
+my_image = torch.tensor(
+    [[0, 0, 0, 0, 0, 0],
+     [0, 1, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0]]
+)
+
+# shift the image by 1 pixel in dim 0, 2 pixels in dim 1
+shifted_image = fourier_shift_image_2d(image=my_image, shifts=torch.tensor([1, 2]))
+```
+
+## Notes
+- shifts can be applied to arrays of 3D images `(..., d, h, w)`
+- arrays of 3D shifts are supported `(..., 3)`
+
+::: torch_fourier_shift.fourier_shift_image_3d

docs/index.md

@@ -0,0 +1,42 @@
+# Overview
+
+*torch-fourier-shift* is a package for shifting 2D and 3D images with subpixel precision 
+by applying phase shifts to Fourier transforms in PyTorch.
+
+<figure markdown>
+  ![A very simple example](./assets/shift_2d_image.png){ width="500" }
+  <figcaption>Shifting a 2D image with torch-fourier-shift</figcaption>
+</figure>
+
+
+```python
+import torch
+from torch_fourier_shift import fourier_shift_image_2d
+
+# create a dummy image
+my_image = torch.tensor(
+    [[0, 0, 0, 0, 0, 0],
+     [0, 1, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0],
+     [0, 0, 0, 0, 0, 0]]
+)
+
+# shift the image by 1 pixel in dim 0, 2 pixels in dim 1
+shifted_image = fourier_shift_image_2d(image=my_image, shifts=torch.tensor([1, 2]))
+```
+
+## Installation
+
+*torch-fourier-shift* is available on PyPI.
+
+```shell
+pip install torch-fourier-shift
+```
+
+## Usage
+
+Please check the examples linked in the sidebar
+
+

mkdocs.yml

@@ -0,0 +1,76 @@
+site_name: teamtomo/torch-fourier-shift
+site_url: https://teamtomo.org/torch-fourier-shift
+site_author: teamtomo
+site_description: >-
+  Documentation for torch-fourier-shift
+repo_name: teamtomo/torch-fourier-shift
+repo_url: https://github.com/teamtomo/torch-fourier-shift
+edit_uri: edit/main/docs/
+copyright: Copyright © 2024 - 2024 teamtomo
+
+
+# Custom navigation can be specified
+nav:
+  - Overview: index.md
+  - I want to:
+      - Shift 2D Image(s): examples/shift_image_2d.md
+      - Shift 3D Image(s): examples/shift_image_3d.md
+      - Shift 2D Fourier Transform(s): examples/shift_dft_2d.md
+      - Shift 3D Fourier Transform(s): examples/shift_dft_3d.md
+
+
+theme:
+  icon:
+    logo: material/cube-outline
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: blue
+      accent: blue
+
+  features:
+    - navigation.instant
+    - navigation.expand
+    - search.highlight
+    - search.suggest
+    - content.tabs.link
+
+markdown_extensions:
+  - admonition
+  - tables
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - attr_list
+  - pymdownx.superfences
+  - pymdownx.highlight
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - md_in_html
+  - pymdownx.arithmatex:
+      generic: true
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://numpy.org/doc/stable/objects.inv
+          options:
+            show_root_heading: true # default is false
+            docstring_style: "numpy"
+            line_length: 50 # default is 60
+            # show_if_no_docstring: true # default is false
+            # show_signature: false  # default is true
+            show_signature_annotations: true # default is false
+            annotations_path: "source" # default is 'brief'
+            show_bases: false # default is true
+            show_source: true # default is true
+            docstring_section_style: table
+            merge_init_into_class: true

pyproject.toml

@@ -15,9 +15,9 @@ sources = ["src"]
 
 # https://peps.python.org/pep-0621/
 [project]
-name = "torch-phase-shift"
+name = "torch-fourier-shift"
 dynamic = ["version"]
-description = "Translate images by phase shifting Fourier transforms in PyTorch"
+description = "Shift 2D/3D images by phase shifting Fourier transforms in PyTorch"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "BSD-3-Clause" }
@@ -54,6 +54,10 @@ dev = [
     "rich",  # https://github.com/Textualize/rich
     "ruff",
 ]
+docs = [
+    "mkdocs-material",
+    "mkdocstrings[python]"
+]
 
 [project.urls]
 homepage = "https://github.com/alisterburt/torch-phase-shift"
@@ -63,10 +67,10 @@ repository = "https://github.com/alisterburt/torch-phase-shift"
 # https://peps.python.org/pep-0621/#entry-points
 # same as console_scripts entry point
 # [project.scripts]
-# torch-phase-shift-cli = "torch_phase_shift:main_cli"
+# torch-phase-shift-cli = "torch_fourier_shift:main_cli"
 
 # [project.entry-points."some.group"]
-# tomatoes = "torch_phase_shift:main_tomatoes"
+# tomatoes = "torch_fourier_shift:main_tomatoes"
 
 # https://docs.astral.sh/ruff
 [tool.ruff]

src/torch_fourier_shift/__init__.py

@@ -0,0 +1,2 @@
+from .fourier_shift_dft import fourier_shift_dft_2d, fourier_shift_dft_3d
+from .fourier_shift_image import fourier_shift_image_2d, fourier_shift_image_3d

src/torch_phase_shift/fftfreq_grids.py → src/torch_fourier_shift/fftfreq_grids.py

@@ -5,7 +5,7 @@
 import einops
 import torch
 
-from torch_phase_shift.dft_utils import rfft_shape
+from torch_fourier_shift.dft_utils import rfft_shape
 
 
 def fftfreq_grid_2d(

src/torch_phase_shift/phase_shift_dft.py → src/torch_fourier_shift/fourier_shift_dft.py

@@ -3,7 +3,7 @@
 from .phase_shift_grids import phase_shift_grid_2d, phase_shift_grid_3d
 
 
-def phase_shift_dft_2d(
+def fourier_shift_dft_2d(
     dft: torch.Tensor,
     image_shape: tuple[int, int],
     shifts: torch.Tensor,
@@ -39,7 +39,7 @@ def phase_shift_dft_2d(
     return dft * phase_shifts
 
 
-def phase_shift_dft_3d(
+def fourier_shift_dft_3d(
     dft: torch.Tensor,
     image_shape: tuple[int, int, int],
     shifts: torch.Tensor,

src/torch_phase_shift/phase_shift_image.py → src/torch_fourier_shift/fourier_shift_image.py

@@ -1,9 +1,9 @@
 import torch
 
-from .phase_shift_dft import phase_shift_dft_2d, phase_shift_dft_3d
+from .fourier_shift_dft import fourier_shift_dft_2d, fourier_shift_dft_3d
 
 
-def phase_shift_image_2d(image: torch.Tensor, shifts: torch.Tensor):
+def fourier_shift_image_2d(image: torch.Tensor, shifts: torch.Tensor):
     """Translate one or more 2D images by phase shifting their Fourier transforms.
 
     Parameters
@@ -20,7 +20,7 @@ def phase_shift_image_2d(image: torch.Tensor, shifts: torch.Tensor):
     """
     h, w = image.shape[-2:]
     image = torch.fft.rfftn(image, dim=(-2, -1))
-    image = phase_shift_dft_2d(
+    image = fourier_shift_dft_2d(
         image,
         image_shape=(h, w),
         shifts=shifts,
@@ -31,15 +31,15 @@ def phase_shift_image_2d(image: torch.Tensor, shifts: torch.Tensor):
     return torch.real(image)
 
 
-def phase_shift_image_3d(image: torch.Tensor, shifts: torch.Tensor):
+def fourier_shift_image_3d(image: torch.Tensor, shifts: torch.Tensor):
     """Translate one or more 3D images by phase shifting their Fourier transforms.
 
     Parameters
     ----------
     image: torch.Tensor
-        `(..., h, w)` image(s).
+        `(..., d, h, w)` image(s).
     shifts: torch.Tensor
-        `(..., 3)` array of 2D shifts in `d`, `h` and `w`.
+        `(..., 3)` array of 3D shifts in `d`, `h` and `w`.
 
     Returns
     -------
@@ -48,7 +48,7 @@ def phase_shift_image_3d(image: torch.Tensor, shifts: torch.Tensor):
     """
     d, h, w = image.shape[-3:]
     image = torch.fft.rfftn(image, dim=(-3, -2, -1))
-    image = phase_shift_dft_3d(
+    image = fourier_shift_dft_3d(
         image,
         image_shape=(d, h, w),
         shifts=shifts,

tests/test_phase_shift_2d.py

@@ -1,7 +1,7 @@
 import torch
 
-from torch_phase_shift import phase_shift_image_2d
-from torch_phase_shift.phase_shift_grids import phase_shift_grid_2d
+from torch_fourier_shift import fourier_shift_image_2d
+from torch_fourier_shift.phase_shift_grids import phase_shift_grid_2d
 
 
 def test_get_phase_shifts_2d_full_fft():
@@ -36,23 +36,23 @@ def test_phase_shift_images_2d():
 
     # +1px in each dimension
     shifts = torch.ones((1, 2))
-    shifted = phase_shift_image_2d(image, shifts)
+    shifted = fourier_shift_image_2d(image, shifts)
     expected = torch.zeros((4, 4))
     expected[3, 3] = 1
     assert torch.allclose(shifted, expected, atol=1e-5)
 
     # +1px in y
     shifts = torch.zeros((1, 2))
     shifts[0, 0] = 1
-    shifted = phase_shift_image_2d(image, shifts)
+    shifted = fourier_shift_image_2d(image, shifts)
     expected = torch.zeros((4, 4))
     expected[3, 2] = 1
     assert torch.allclose(shifted, expected, atol=1e-5)
 
     # +1px in x
     shifts = torch.zeros((1, 2))
     shifts[0, 1] = 1
-    shifted = phase_shift_image_2d(image, shifts)
+    shifted = fourier_shift_image_2d(image, shifts)
     expected = torch.zeros((4, 4))
     expected[2, 3] = 1
     assert torch.allclose(shifted, expected, atol=1e-5)