Skip to content

FDK reconstruction, faster voxel-driven projector, launch layouts - #19

Merged
nHackel merged 14 commits into
mainfrom
nh/fdk
Nov 15, 2026
Merged

nHackel merged 14 commits into
mainfrom
nh/fdk

Conversation

@nHackel

@nHackel nHackel commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Summary

  • FDK: filtered back projection for circular scans (Feldkamp, Davis & Kress 1984): cone beams with a flat or arc detector, and parallel beams. It works on the CPU and on GPUs, and builds on the voxel-driven back projection.
  • Redundancy weighting as dispatch types: FullScan, ParkerWeights for short scans (Parker 1982, in the form of Wesarg et al. 2002), ArrayRedundancy for weights computed elsewhere, or your own subtype of AbstractRedundancy.
  • Voxel-driven projector, about 4× faster on the CPU:
    • per-view projection matrices;
    • runs of voxels per thread.
  • LaunchConfig gets a projector-specific layout, and fields left at nothing are derived. Breaking: tile is renamed to layout.
  • Docs: two how-tos, an explanation page on filtered back projection, and an updated page on launch settings.
  • Benchmarks: the voxel-driven projector joins the projector suites, and there's a new reconstruction suite comparing with Sinograms.jl.

FDK

  • FDK(image, geometry; redundancy, window, cutoff, eltype, storage, launch) builds a plan: the filter, FFT plans (FFTL.jl) and buffers. plan * y reconstructs.
  • CTOperators.fdk(image, geometry, y) is the one-call form, public but not exported.
  • Inputs:
    • Circular scans are checked: source on a circle about the axis, detector columns along the axis, flat detector perpendicular to the central ray, equal cell spacing. Violations give an ArgumentError.
    • Geometries from Sinograms.jl work through projection_geometry. With Sinograms.jl loaded, its fdk also accepts our plans and geometries (package extension).
  • Filter: the ramp with windows (:ramp, :hann as the default, :hamming, :cosine, :shepplogan, or any callable w(f)) and a cutoff.
  • Redundancy:
    • FullScan for full turns.
    • ParkerWeights for scans from π + fan angle up to one turn.
    • ArrayRedundancy(weights, views) for weights per data element and per view.
    • Your own AbstractRedundancy needs redundancy_weights (host) and redundancy_weight (kernel).
  • Devices:
    • Plans move between devices with adapt(storage, plan).
    • Redundancy objects with arrays move with adapt(storage, weight).
    • Voxel-driven scales with per-view data now follow adapt and subset.

Voxel-driven projector and launch settings

  • Per-view tables: project_point is computed from tables built once per view.

    • ConeBeam: a 3 × 4 projection matrix, with cu = a/c, cv = b/c and magnification 1/c.
    • ParallelBeam: an affine map.
    • ArcConeBeam: project_point of the geometry, as before.
  • Runs of R voxels along x per thread: within a run, the matrix row values of a voxel follow from its neighbor by adding a step.

  • LaunchConfig(; workgroupsize=nothing, layout=nothing):

    • What layout means depends on the projector, and each projector checks what it accepts: tiles (tu, tv) for Siddon, Joseph and distance-driven, runs (R,) for voxel-driven and FDK. Anything else gives an ArgumentError.
    • nothing means derived. The layout is the device default. The workgroup size is one tile per workgroup if the device allows it (KernelInterface.max_work_group_size), otherwise KernelAbstractions' choice.
    • An explicit workgroup size is used as given; one that is too large fails at launch.
  • Defaults:

    • ray-driven projectors: tiles of 8 × 8 on GPUs, as before;
    • voxel-driven projector: runs of 8 on the CPU, runs of 2 on GPUs.

    No workgroup size in the defaults is tuned to a particular GPU.

Docs

  • How-to "Reconstruct with FDK": windows, short scans with Parker weights, FDK as the start image for CGNR.
  • How-to "Write FDK Windows and Weights": a window of your own, Parker weights from Sinograms.jl through ArrayRedundancy, and the weighting of Wesarg et al. as a custom AbstractRedundancy.
  • Explanation "Filtered Back Projection": the back projection of a point, the ramp filter, and the fan- and cone-beam weights.
  • "Workgroups, Ray Order and Runs of Voxels" (renamed from "Workgroups and Ray Order on GPUs"), and an "Implementation" section on the voxel-driven page.

Results

Ryzen 9 9900X with 24 threads, RX 7900 XT, Float32. 128³ voxels, 360 views, 256 × 128 cells.

24 threads 1 thread ROCm error
FDK 0.18 s 2.2 s 12 ms 0.053
Sinograms fdk 0.86 s 6.9 s – 0.042
Sinograms fdk, decon1=false 0.82 s 6.9 s – 0.053

Sinograms' default filter divides by sinc² (decon1=true); without that, the errors are equal.

Voxel-driven back projection on the same scan, default launch:

before after
CPU 864 ms 205 ms
ROCm 19.3 ms 13.5 ms

Details and reproduction are in benchmark/README.md: bench.jl run fdk and tune_launch.jl.

Tests

  • FDK:
    • the volume is conserved (Feldkamp's property, within 0.07% for flat and parallel geometries);
    • short scans against full scans;
    • Parker weights equal 1 where lines are measured once;
    • ArrayRedundancy, adapt, and a run on each device.
  • Voxel-driven:
    • the tables match project_point of the geometry to 1e-12;
    • runs match single voxels, including odd sizes, masks, 2D images and all detector types.
  • Launch: layout checks per projector, derived settings, and that too-large workgroups fail.
  • Results:
    • CPU: 11383 of 11383 passed;
    • ROCm (test/gpu/run.jl rocm): 1406 of 1406 passed.

Notes

  • New dependency: FFTL.jl. Its compat requires KernelAbstractions 0.10; RegularizedLeastSquares, LinearOperatorCollection and JLArrays resolve with it.
  • JLArrays test run: test/gpu/run.jl jlarrays doesn't resolve until LinearOperators allows JLArrays 0.5 The code path was checked with JLArrays in a separate environment.
  • CUDA adapters: the CUDA adapters of the benchmarks are written but not run (no NVIDIA GPU available).

🤖 Generated with Claude Code

nHackel and others added 14 commits November 11, 2026 21:04
VoxelDrivenProjector projects each voxel center onto the detector and spreads it over the 2 x 2
nearest cells by bilinear interpolation (one thread per voxel, loop over the views); the back
projection gathers with the same weights, so it is the exact adjoint and needs no atomics. The
per-view scale of the weights is injectable (AbstractVoxelScale, voxel_scale); the default
LineIntegralScale makes the forward projection approximate the mean of the line integrals over each
cell, UnitScale keeps the plain interpolation weights.

Geometry: project_point(g, p, k) -> DetectorHit, the inverse of cell_ray, for ConeBeam, ArcConeBeam
and ParallelBeam, with magnification and projection density.

Tests: the projector (contract, mass of a voxel, comparison with distance driven, 2D, unit scale),
project_point (inverse of cell_ray, density against a finite-difference Jacobian), and the voxel-
driven projector in the masks, device, launch, precision and extension tests. The precision test
bounds the error of atomic additions in Float16/BFloat16 data by the number of additions per cell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New explanation page Voxel-Driven Method: an interactive figure of one pixel in a fan beam, the two
factors of the weights, the derivation of the line-integral scale (marked as ours, citing the weight
factors named by De Man & Basu 2004), the 2D form, a custom scale, a uniform-disk check of small
cells after Miao (2013), coverage, properties and references.

System Matrix: voxel-driven row in the table and a static figure of the pieces of a ray per
principal axis; the interactive principal-axis figure shows only its left panel, which keeps the
page responsive. Comparing Projectors, README, index, API page and navigation list the new
projector. Reviewed by two cold review agents; their findings are applied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A scale may hold arrays: adapt of a VoxelDrivenProjector now moves its scale along, and subset
passes it through subset(scale, views) (unchanged by default), so scales with one value per view
keep their views. The default workgroup size comes from launch_config, as for the other
projectors.

Tests: a 2D image or a 3D one with nz = 1 against a multi-row flat or arc detector (row sums
equal to the distance-driven projector's, rows outside the slab 0), custom scales (isbits, and
per view with subset and adapt), and the error model behind the tolerances of the comparisons with
the distance-driven projector.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
FDK(image, geometry; redundancy, window, cutoff, eltype, storage, launch) reconstructs a circular
cone-beam scan (flat or arc detector) with the method of Feldkamp, Davis & Kress (1984), and a
parallel-beam scan with filtered back projection: cosine weight, ramp filter along the detector
rows (FFTL.jl, on any device), voxel-driven back projection with the weight of each view and the
squared magnification. CTOperators.fdk(image, geometry, y) is the one-call form (public, not
exported); the Sinograms extension adds methods of Sinograms.fdk for the types of this package.

The geometry is checked to be a circular scan (CircularScan, computed on the host). How lines
measured more than once are weighted is an AbstractRedundancy: FullScan (the default, views around
the whole circle, uneven steps allowed) and ArrayRedundancy (weights given as arrays). adapt moves
a plan to another device with new buffers and FFT plans.

Tests: filter, scan checks, redundancy weightings, reconstructions of a disk and an ellipsoid from
exact line integrals (flat, arc, detector offsets, parallel beam, all windows, image mask), with
bounds from an error model (volume against the exact volume; Feldkamp's conservation along the
axis for flat detectors), the comparison with Sinograms.jl, and the devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
How-to "Reconstruct with FDK": a 3D Shepp-Logan phantom reconstructed with FDK, the windows of the
filter, the FDK image as the start of CGNR, and the requirements on the scan. Explanation "Filtered
Back Projection": back projection and filtered back projection of a point with 2 to 180 views, the
1/r blur of the back projection, the ramp filter, and what fan and cone beams add. API: the FDK
section of the projectors page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ParkerWeights() weights the lines that a short scan measures twice (Parker 1982), for scans from
pi plus the fan angle up to one turn: Delta = (span - pi) / 2 in place of half the fan angle
(Wesarg et al. 2002, Eq. 15), either direction of rotation, any start angle, uneven steps. The
kernel computes the weight from the angle of the view and the fan angle of the cell in the plane
of the orbit. redundancy_weights now gets the geometry of the plan (element type, device), so
built-in weightings put their arrays on the device in the plan's element type.

Docstrings: short scans, truncation not detected, FullScan's view weights, "data element", a
docstring for CTOperators.fdk, links to the explanation of filtered back projection.

Tests: the weights of every line sum to 1 (to rounding), fan angles of a flat detector, view
weights, rejected scans, short-scan reconstructions (flat, arc, reversed, overscan, parallel beam)
with bounds from the measured discretization error, and the devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
How-to "Reconstruct with FDK": a short scan with Parker weights and a figure of the weights, what
the slices and the window profiles show, the errors of the windows on noise-free data, the CGNR
iterations counted from 0, the requirements with Parker weights and undetected truncation, and
the references. Explanation "Filtered Back Projection": the back projection as rows of the system
matrix, the magnification for flat and arc detectors, "data element", and smaller fixes from a
cold review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New how-to "Write FDK Windows and Weights" under Custom Components: a window of its own (a callable
struct and a function), Parker weights of Sinograms.jl passed through ArrayRedundancy, and a
weighting type of its own (Wesarg et al. 2002) built on the public CircularScan, cell_ray and
redundancy_weights. The FDK how-to and the FDK docstring describe instead of explaining and link to
the new page. Adapt joins the docs environment for the example type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
benchmark/fdk.jl times FDK of CTOperators (CPU and ROCm) and fdk of Sinograms.jl on a circular scan
of 128^3 voxels and 360 views, in its own environment so that Sinograms.jl stays out of the shared
one. The README lists setup, runtime with 24 and 1 threads, and the errors; the difference in error
comes from the default decon1=true of Sinograms.jl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Kak & Slaney 1988 is not in our document collection and was not read, so it is no longer cited for
claims: the FDK docstring, the header comments of fdk.jl and filter.jl and the Filtered Back
Projection page list it under "See also"; the parenthetical citations on that page are removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LaunchConfig{N}(workgroupsize, layout::NTuple{N,Int}) replaces the tile field. Each projector
documents and checks the layout it accepts: the ray-driven projectors () or (tu, tv) tiles of
detector cells, the voxel-driven projector and FDK () or (R,) runs of R voxels along x per thread;
other lengths give an ArgumentError.

The voxel-driven projector computes project_point from per-view tables built once on the host:
a 3 x 4 matrix for ConeBeam (cu = a / c, cv = b / c, magnification 1 / c), an affine map for
ParallelBeam; ArcConeBeam keeps project_point of the geometry. Within a run, a, b, c of a voxel
follow from those of its neighbor by adding a step (view_run, run_hit). No branch per voxel in the
run loop, 2D or 3D decided on the host. Defaults: runs of 8 on the CPU, runs of 2 in workgroups of
64 on GPUs. FDK copies the filtered rows with a kernel instead of a broadcast.

Measured (128^3 voxels, 360 views, 256 x 128 cells, Float32): back projection CPU 864 -> 205 ms,
ROCm 19.3 -> 12.7 ms; FDK CPU 0.89 -> 0.19 s (24 threads), 9.0 -> 2.1 s (1 thread), ROCm 21 -> 12
ms. benchmark/voxeldriven.jl and the README sections. Tests: tables against project_point of the
geometry, runs against single voxels (odd sizes, masks, 2D, all detector types), layout checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LaunchConfig(; workgroupsize=nothing, layout=nothing): `nothing` now means "derived" in both
fields, so that giving one field no longer drops the default of the other. Per value one function
family: launch_layout(op, launch, geometry, backend) takes the configuration's layout or the
projector's default launch_layout(op, geometry, backend); launch_workgroupsize(op, launch, layout,
backend) takes the configuration's size or the projector's launch_workgroupsize(op, layout), an Int
or nothing, if it is at most KernelInterface.max_work_group_size(backend), otherwise nothing
(KernelAbstractions' choice). The ray-driven projectors (RayDrivenProjector) ask for one tile per
workgroup (tu * tv), the voxel-driven projector for none.

Defaults: ray-driven on GPUs tiles of 8 x 8 cells in workgroups of 64 (derived from the tile, as
before), on the CPU data order; voxel-driven runs of 8 voxels on the CPU and one voxel per thread on
GPUs, with KernelAbstractions' workgroups (before: runs of 2 in workgroups of 64). A workgroup size
given larger than the device allows is not changed: KernelAbstractions rejects it at the launch
with an ArgumentError, now tested on the CPU and on the devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The voxel-driven projector (and FDK) takes runs of 2 voxels on GPUs by default, in the workgroups
KernelAbstractions chooses: FDK on ROCm 16.6 -> 12.0 ms (128^3, 360 views). FDK names itself in the
error for a wrong layout. benchmark/fdk.jl takes the run length as an optional second argument.

The explanation page is now "Workgroups, Ray Order and Runs of Voxels" and describes the derived
settings (`nothing`: the device's layout, one tile per workgroup if the device allows it, otherwise
KernelAbstractions' choice; a too large size given fails with an ArgumentError). Fixes from the
cold review: ray-driven and voxel-driven projectors distinguished where threads, atomics and
results are described (launch page, GPU how-to, voxel-driven page and docstring); benchmark numbers
on the launch page replaced by the link to benchmark/README.md; unshown claims about the prototype
removed (README, projection.jl); the fan-beam weights on the FBP page cite Feldkamp et al. 1984,
Section 2 (flat detector). README: ROCm columns re-measured with the new defaults, the FDK scale
noted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The voxel-driven projector joins the projector suites (adapters ctoperators-voxeldriven, -rocm,
-cuda, detector geometries only). FDK becomes a reconstruction suite `fdk` with the problem fdk128
(the circular scan of the former benchmark/fdk.jl): the worker measures adapters that define
reconstruct! by setup time, reconstruction time and error against the phantom image, with a CSV
header of their own; libraries ctoperators-fdk (-rocm, -cuda), sinograms-fdk and
sinograms-fdk-nodecon1 in envs/sinograms (formerly envs/fdk), whose CtFanFlat geometry is checked to
be the problem's. bench.jl keeps projectors and reconstructions to their suites.

tune_launch.jl times all four projectors and FDK, also on the CPU, with the layouts of each (tiles
of detector cells, runs of voxels). benchmark/voxeldriven.jl and benchmark/fdk.jl are removed; the
README sections are measured anew with the suite and tune_launch.jl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nHackel nHackel changed the title Nh/fdk FDK reconstruction, faster voxel-driven projector, launch layouts Nov 15, 2026
@nHackel
nHackel marked this pull request as ready for review November 15, 2026 11:33
@nHackel
nHackel merged commit 8586eb4 into main Nov 15, 2026
1 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant