Some refactoring

.github/workflows/CI.yml

@@ -16,21 +16,21 @@ on:
       - Project.toml
 jobs:
   test:
-    name: Julia ${{ matrix.julia-version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Julia ${{ matrix.julia-version }} - ${{ matrix.os }} - ${{ matrix.julia-arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [windows-latest, macos-latest]
-        julia-version: ['1.10', 'lts']
-        arch:
-          - x64
+        julia-arch: [x64]
+        julia-version: ['1.10','1.11','1.12', 'lts']
+
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.julia-version }}
-          arch: ${{ matrix.arch }}
+          arch: ${{ matrix.julia-arch }}
       - uses: actions/cache@v4
         env:
           cache-name: cache-artifacts
@@ -45,7 +45,7 @@ jobs:
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@v1
       - name: Resolve/Update dependencies
-        run: julia -e 'using Pkg; Pkg.resolve()' # Or Pkg.update()
+        run: julia -e 'using Pkg; Pkg.activate("."); Pkg.instantiate(); Pkg.update();' # Or Pkg.update()
       - uses: julia-actions/julia-runtest@v1
         with:
           annotate: true

.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.12'
+      - name: Install project environment
+        run: |
+          echo "GITHUB_WORKSPACE=$GITHUB_WORKSPACE"
+          julia --project="${{ github.workspace }}" -e 'using Pkg; Pkg.instantiate(); Pkg.precompile()'
+      - name: Build documentation
+        run: julia --project=. docs/make.jl
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build

.gitignore

@@ -2,4 +2,6 @@
 test/.ipynb_checkpoints
 test/*.ipynb
 Manifest.toml
-Manifest-v1.11.toml
+Manifest-v1.11.toml
+*.txt
+docs/build/

Project.toml

@@ -3,8 +3,12 @@ uuid = "c853eca7-4467-4dac-871a-88cef1644acc"
 version = "1.0.0"
 authors = []
 
+[workspace]
+projects = ["test", "docs"]
+
 [deps]
 AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
@@ -17,24 +21,24 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [weakdeps]
-AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"
-FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
-[extras]
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" # UUID for the standard library Test
-AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"
-
 [compat]
 AbstractFFTs = "1"
+Documenter = "1.16.1"
 FFTW = "1"
 FileIO = "1"
 ImageIO = "0.6"
 ImageMagick = "1"
 Images = "0.26"
-MAT = "0.10, 0.11"
+MAT = "0.10"
 Plots = "1"
 Statistics = "1"
 
+[extras]
+AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
 [targets]
 test = ["Test", "FFTW", "AbstractFFTs"]

README.md

@@ -121,6 +121,31 @@ iphlct = iphlct2d(phlct, n)
 
 Reference: [Professor Saito's paper][paper] page 30 Chapter 6.2.2.
 
+## Examples
+
+Basic DST/IDST round-trip:
+
+```julia
+using .PolyHarmonicTrigTransforms
+
+x = randn(8)
+y = dst(x)
+x_rec = idst(y)
+@assert maximum(abs.(x_rec - 4 .* x ./ 4)) < 1e-12 # numeric check
+```
+
+PHLCT forward/backward round-trip (block size `N`):
+
+```julia
+using .PolyHarmonicTrigTransforms
+
+n = 8
+img = randn(n, n)
+coeffs = phlct_forward(img, n)
+img_rec = phlct_backward(coeffs, n)
+@assert norm(img - img_rec) / norm(img) < 1e-12
+```
+
 #### Image Testing
 
 To test images, first take your chosen image and convert it into a square image (i.e. size n x n where n is the new size of the image after using tools to square it).

docs/Project.toml

@@ -0,0 +1,9 @@
+name = "PolyHarmonicTrigTransformsDocs"
+uuid = "00000000-0000-0000-0000-000000000001"
+authors = ["UCD4IDS"]
+
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "1.16.1"

docs/make.jl

@@ -0,0 +1,17 @@
+using Documenter
+using PolyHarmonicTrigTransforms
+
+makedocs(
+    modules = [PolyHarmonicTrigTransforms],
+    sitename = "PolyHarmonicTrigTransforms.jl",
+    pages = [
+        "Home" => "index.md",
+        "API"  => "api.md",
+    ],
+    format = Documenter.HTML(),
+    clean = true,
+    debug = true,
+    checkdocs = :none, # disable docstring checks to avoid failing on undocumented symbols
+)
+
+println("Documentation built: $(joinpath(@__DIR__, "build"))")

docs/src/api.md

@@ -0,0 +1,8 @@
+# API Reference
+
+This page documents the package API automatically.
+
+```@autodocs
+Modules = [PolyHarmonicTrigTransforms]
+Order = [:modules, :types, :functions]
+```

docs/src/index.md

@@ -0,0 +1,15 @@
+# PolyHarmonicTrigTransforms
+
+Short overview: polyharmonic and trigonometric transform utilities for signal and image processing.
+
+## Quick start
+
+```julia
+using PolyHarmonicTrigTransforms
+using Random
+
+v = rand(8)
+dst(v)
+```
+
+See the API reference generated from docstrings for detailed usage of `dst`, `idst`, `llst2d`, and other exported functions.

src/dst.jl

@@ -30,23 +30,83 @@
 # See also: IDST
 
 module DST
-    using AbstractFFTs, FFTW
+    function _ensure_fftw()
+        if !isdefined(@__MODULE__, :FFTW)
+            Core.eval(Main, :(using FFTW))
+            Core.eval(@__MODULE__, :(const FFTW = Main.FFTW))
+        end
+        return nothing
+    end
 
-    export dst, dst_old
+    export dst, dst!, dst_u, plan_dst, dst_old
+
+    """
+    dst(x; dims=1)
+
+    Compute the Type-I Discrete Sine Transform (DST) of `x` along `dims`.
 
+    Arguments
+    - `x`: an `AbstractArray` (vector or matrix).
+    - `dims`: dimension to transform (default `1`).
+
+    Returns
+    - transformed array of the same shape as `x`.
+
+    Example
+    ```julia
+    y = dst([1.0,2.0,3.0])
+    ```
+    """
     function dst(x::AbstractArray, dims=1)
+        _ensure_fftw()
         N = size(x, dims)
         return FFTW.r2r(x, FFTW.RODFT00, dims) / 2
     end
 
     function dst_u(x::AbstractArray, dims=1)
+        _ensure_fftw()
         N = size(x, dims)
         new_x = FFTW.r2r(x, FFTW.RODFT00, dims)
 
         return new_x / (sqrt(2*N)) #unitory value
     end
 
+    """
+    plan_dst(x; dims=1, flags=FFTW.MEASURE)
+
+    Create an FFTW r2r plan for the DST (RODFT00) on `x`. The returned plan
+    can be executed with `plan * x`.
+    """
+    function plan_dst(x::AbstractArray; dims=1, flags=FFTW.MEASURE)
+        _ensure_fftw()
+        return FFTW.r2r_plan(x, FFTW.RODFT00, dims; flags=flags)
+    end
+
+    """
+    dst!(x; dims=1)
+
+    In-place DST that overwrites `x` with its transform when possible. Falls
+    back to a safe out-of-place compute and copy if the in-place routine is
+    not available on the current platform.
+    """
+    function dst!(x::AbstractArray; dims=1)
+        _ensure_fftw()
+        try
+            # Try to use FFTW in-place r2r if available
+            FFTW.r2r!(x, FFTW.RODFT00, dims)
+            x .*= 0.5
+            return x
+        catch _
+            # Fallback: compute out-of-place and copy into x
+            tmp = FFTW.r2r(x, FFTW.RODFT00, dims)
+            tmp .*= 0.5
+            x .= tmp
+            return x
+        end
+    end
+
     function dst_old(a::AbstractArray, n=nothing)
+        _ensure_fftw()
         if minimum(size(a)) == 1
             if size(a, 2) > 1
                 do_trans = 1
@@ -73,7 +133,7 @@ module DST
         y = zeros(2 * (n + 1), m)
         y[2:n+1, :] = aa
         y[n+3:2*(n+1), :] = -reverse(aa, dims=1)
-        yy = fft(y, (1,))
+        yy = FFTW.fft(y, (1,))
         b = yy[2:n+1, :] / (-2 * sqrt(-1 + 0im))
 
 

src/helper.jl

@@ -26,6 +26,13 @@ module HELPER
 
   export drawpartition2d2, l2norm, is_level_list_valid, is_valid_subband
 
+  """
+  drawpartition2d2(signal, liste; width=nothing, image=nothing, fit=false)
+
+  Draw the quadtree partition described by `liste` over `signal` (image).
+  Optional keyword `width` controls line width; `image` may be a filename to overlay.
+  Returns a `Plots.Plot` object.
+  """
   function drawpartition2d2(signal::AbstractMatrix, liste::AbstractMatrix; width=nothing, image=nothing,  fit=false)
     (m, n) = size(signal)
 
@@ -77,10 +84,21 @@ module HELPER
     newpos = recurspartition(p, pm + m / 2, pn + n / 2, m / 2, n / 2, liste, newpos, level + 1, width)
   end
 
+  """
+  l2norm(original, mutated)
+
+  Relative L2 error: returns norm(mutated - original) / norm(original).
+  """
   function l2norm(original::AbstractVecOrMat, mutated::AbstractVecOrMat) 
     return norm(mutated .- original)/ norm(original)
   end
 
+  """
+  is_level_list_valid(signal, list)
+
+  Quick validator that checks `signal` dimensions are even and that `list` is a valid level-list.
+  Returns `true` when valid, otherwise `false`.
+  """
   function is_level_list_valid(signal::AbstractMatrix, list::AbstractMatrix)
     m,n = size(signal)