Skip to content

Faster holographic reconstruction, a hologram simulator, and holo fixes - #452

Open
animmosmith wants to merge 12 commits into
mainfrom
hologram-autumn26
Open

animmosmith wants to merge 12 commits into
mainfrom
hologram-autumn26

Conversation

@animmosmith

@animmosmith animmosmith commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Housekeeping

Features and enhancements

  • pyopia.simulator.holo simulates in-line holograms of opaque disks at known position, depth and size, writes a folder of them with their true particles, and matches processed statistics back to the truth. Replaces Add a hologram simulator for testing reconstruction settings #449 (fd3d02d). Refs Consider tests with synthetic data and statistical size distributions #199
  • The image stack and the kernel are stored plane-first, shape (planes, rows, columns), so each plane is contiguous in memory; the kernel build is 30% faster and inverse_transform 38% faster on its own (3723b42)
  • The reconstruction multiplies the half spectrum of the real hologram by the cosine of the propagation phase and uses rfft2/irfft2; the stack is unchanged apart from rounding, and odd image sizes are now reconstructed at the true FFT frequencies (026d9d5)
  • The kernel is generated plane by plane with a cosine recurrence, restarted from exact cosines every 13 planes (at most 8e-12 from exact cosines), so the full kernel is no longer held in memory (0b6bcae)
  • The kernel is held on the non-negative frequencies only and the plane loop reuses its buffers (7748be8)
  • Reconstruct(dtype='float32') runs the transforms, kernel and stack in single precision; the default stays 'float64' (891a53f)
  • Reconstruct(workers=N) reconstructs blocks of planes on N threads; the default workers=1 is unchanged (da3b56b)
  • find_focus_sobel takes the edge magnitude a chunk of planes at a time with the new sobel_stack (bit-identical to skimage.filters.sobel per plane); a 520 x 520 box in a 101-plane stack needs 19 MB extra instead of 215 MB (e5adedc)

Behaviour changes

  • data['im_stack'] and data['kern'] are (planes, rows, columns); code that indexes the old (rows, columns, planes) layout must change.
  • forward_transform returns the half spectrum, create_kernel(shape, ...) takes the image shape and returns a Kernel, and inverse_transform takes the half spectrum and a Kernel; direct callers of these three functions must change. Reconstruct's config parameters are unchanged apart from the two new optional ones (dtype, workers).
  • Odd image sizes are reconstructed at the true FFT frequencies (the previous kernel was shifted by half a frequency bin).
  • Configs using increase_depth_of_field = true give different results because of the slice fix. On the 35 example holograms (Sobel focus) the particle count goes from 4141 to 4150 and 24 of the 25 processed images differ.
  • float32 can differ from float64 for pixels at the stack_clean cut-off, and for a segmentation threshold between 0.98 and 1.0 (not tested).

Checks

  • CI green
  • Fast tests on the branch: 101 passed, 27 slow deselected. Full suite including the slow tests and notebooks: 128 passed.
  • All 35 holograms of the sample-data_v2.0.0 release, Reconstruct followed by Focus (max map, 0.97, Sobel focus), segmentation, statistics, with a moving background of 10 images (25 images produce statistics, 4136 particles): every statistics column equals the result from main exactly, for float64 and float32, with 1 and 4 workers.
  • Time for that run in one process on 4 pinned cores: 217 s on main; 65 s float64; 42 s float32; 37 s float32 with workers=4.
  • The reconstruction step alone (1200 x 1600, 101 planes, 4 cores, per hologram after the first, three interleaved rounds): 6.5 s and 4.9 GB peak on main; 2.3 s and 1.8 GB float64; 1.7 s and 1.0 GB float32; 1.4 s and 1.1 GB float32 with workers=4. The first hologram, which builds the kernel, takes 14.9 s on main, 2.4 s float64 and 1.7 s float32.
  • Python 3.12.13, numpy 2.5.1, scipy 1.18.0, scikit-image 0.24.0, Linux x86-64, one machine. Not checked on Windows or macOS.

find_focus_imax and find_focus_sobel sliced planes [ifocus-1:ifocus+1], so
the option combined the focus plane and the one before it only. It now
combines ifocus-1, ifocus and ifocus+1, clipped to the stack.
forward_transform shifts the spectrum but inverse_transform did not shift it
back, so output option 1 returned the real part multiplied by
(-1)**(row+col) for even image sizes. Option 0 squares the result and is
unchanged. Add a test against an independent unshifted calculation.
Compare Reconstruct with an independent per-plane calculation on the
unshifted frequency grid, for the three forward filter options and both
output options, and check the stack_clean cut-off. Even image size only.
pyopia.simulator.holo simulates in-line holograms of opaque disks at known
position, depth and size with the band-limited angular spectrum method
(synthetic_hologram, random_particles). write_synthetic_holograms saves a
folder of holograms with their true particles, and match_to_truth matches
processed statistics back to them, including stats whose index labels repeat
across images. The scattered field is propagated with the correct phase
relative to the incident wave, so the shadow behind an opaque particle is
dark at any distance. Adds tests and a docs entry.
…s, columns)

Each reconstructed plane and each kernel plane is then contiguous in memory.
create_kernel, Reconstruct, inverse_transform, std_map, max_map,
find_focus_imax, find_focus_sobel and Focus index the plane axis first; the
Data docstring and the synthetic stacks in the tests follow. The stack, focus
planes and focused images are identical to the previous layout.
Reconstruct now takes the half spectrum of the real hologram (rfft2) and
multiplies it by the cosine of the propagation phase, creating the stack with
irfft2. The spectrum of a real image is conjugate-symmetric and the phase is
the same at opposite frequencies, so the real part of the field is the
inverse transform of the spectrum times the cosine alone; the squared real
part (output option 0) changes only at rounding level. The kernel uses the
true FFT frequencies, which corrects the half-bin shift that odd image sizes
had.

forward_transform, create_kernel and inverse_transform now work on the half
spectrum: create_kernel takes the image shape and returns the cosine kernel
(planes, rows, columns // 2 + 1). The complex implementations are removed.
…rence

create_kernel returns a Kernel that yields the cosine of the propagation
phase for each plane, using cos(p + dp) = 2 cos(dp) cos(p) - cos(p - dp),
with the first two planes of every block of 13 evaluated exactly. The full
kernel is no longer held in memory, so the peak memory of Reconstruct at
1200 x 1600 and 101 planes falls from 2.6 GB to 1.9 GB.

The kernel is regenerated for every hologram, so each hologram after the
first takes about 19% longer on 4 cores. The planes differ from exact
cosines by at most 8e-12.
…the plane loop

The kernel phase depends on frequency only through its square, so Kernel
generates (rows // 2 + 1, columns // 2 + 1) planes and inverse_transform
multiplies the negative-frequency rows by the same plane in reverse order,
using a view. Kernel writes its planes into three arrays that are reused,
inverse_transform reuses one product array, lets irfft2 overwrite it and
squares each plane straight into the stack, and clean_stack builds its mask
one plane at a time. At 1200 x 1600 and 101 planes on 4 cores, each hologram
after the first takes 2.5 s instead of 2.9 s and the peak memory is 1.75 GB
instead of 1.88 GB. The stack differs from the previous commit by rounding
only.
Reconstruct takes dtype='float64' (default) or 'float32' for the transforms,
kernel and image stack; other values raise a ValueError. The kernel phase is
still calculated in double precision. In float32 the stack differs from
float64 by about 3e-7 of its maximum on a simulated hologram, apart from
pixels at the stack_clean cut-off that can flip, and the focus planes,
bounding boxes and region areas are identical. At 1200 x 1600 and 101 planes
on 4 cores, each hologram after the first takes 1.9 s instead of 2.5 s and
the peak memory is 0.98 GB instead of 1.75 GB.
Reconstruct takes workers=1 (default). With more than one worker the planes
are split into contiguous blocks that are reconstructed on separate threads,
each with its own kernel buffers and a single-threaded transform; the
recurrence restarts at the start of each block, so the stack matches the
serial one within rounding. With one worker nothing changes and each
transform still uses all cores. At 1200 x 1600 and 101 planes on 4 cores,
float32 takes 1.4 s per hologram with four workers instead of 1.8 s, and
float64 takes 2.0 s instead of 2.6 s.
sobel_stack applies the Sobel filter to every plane of a stack with the same
weights, boundary mode and normalisation as skimage.filters.sobel, and gives
bit-identical results. find_focus_sobel takes the edge magnitude for chunks of
about a million pixels, keeps only the per-plane sums, and recomputes the focus
plane (and its neighbours when the depth of field is increased) afterwards, so
a box covering a large part of the frame no longer needs a copy of itself for
every plane. For a 520 x 520 box in a 101-plane float64 stack the extra memory
at peak falls from 215 MB to 19 MB; the time per box is about the same.

This branch has not been deployed

No deployments
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.

inverse_output_option=1 returns the real part with a checkerboard sign increase_depth_of_field leaves out the plane after the focus plane

1 participant