API reference

Abstract execution backend used by ParticleHolography plans.

CPU execution through ordinary Julia arrays and FFTW.

backend()

Return the process-wide default backend. A new Julia process starts with CPU. Call backend(:cpu), backend(:cuda), or backend(:metal) to change it. Explicit backend arguments remain available for side-by-side comparisons.

backend(kind; device=nothing)

Select and return the process-wide default execution backend. kind is :cpu, :cuda, :metal, or :auto. Subsequent calls that omit a backend use this selection. :auto prefers CUDA, then Metal, and always falls back to CPU.

Changing the default while concurrent tasks are running is unsupported. Pass an explicit backend object to each call when CPU and GPU work must coexist.

Return the symbols of backends usable in the current process.

Copy x to b. An input already on b may be returned without copying.

Copy x to the currently selected backend().

Copy an array or wrapped optical value to host memory.

synchronize_backend(backend)

Wait for queued work on an execution backend. Use this before timing GPU work. The longer name avoids collisions with functions exported by CUDA.jl/Metal.jl.

Distance-independent spatial-frequency grid for angular-spectrum propagation.

Distance-dependent angular-spectrum multiplier in FFT-native order.

Complex optical wavefront on any supported execution backend.

Frequency-domain low-pass filter stored in FFT-native order.

propagation_grid([backend], shape, wavelength, pixel_pitch)

Construct the distance-independent spatial-frequency grid used by the angular-spectrum method. shape may be a square side length or (height, width). All length parameters must use the same unit.

propagation_kernel([backend], distance, wavelength, grid)

Construct the angular-spectrum propagation multiplier for distance. The kernel is stored in the order consumed directly by plan_fft.

Create a complex Gabor wavefront from a non-negative intensity image.

pad2d(input[, target_shape]; mode=:mean)

Centre input in a larger 2-D array. The default target is twice each input dimension. mode=:mean fills the border with the input mean; mode=:zero uses zero. The result stays on the input backend.

Reusable Gerchberg-Saxton workspace for a pair of holograms.

phase_retrieval!(plan, hologram1, hologram2; iterations=10)

Run Gerchberg-Saxton phase retrieval using buffers owned by plan. The returned Wavefront aliases the plan workspace and is overwritten by the next call. Use phase_retrieval when an owning copy is required.

Run phase retrieval with plan and return an owning wavefront copy.

ReconstructionRequest(slices; volume=Float32, min_projection=nothing)

Describe the outputs to produce during one depth scan. Real-valued volume types store intensity, complex types store the propagated wavefront, and nothing avoids allocating that output. volume accepts N0f8, Float32, ComplexF32, ComplexF64, or nothing; min_projection accepts N0f8, Float32, or nothing.

Outputs generated together by one reconstruction depth scan.

Conservative memory estimate for a reconstruction plan and output request. required_bytes is the new allocation covered by scope; safe is missing when the backend cannot report available memory.

memory_diagnostic(backend, working_shape, request;
                  output_shape=working_shape, include_plan=true,
                  safety_factor=1.2)

Estimate new plan, output, and conversion allocations before reconstruction. The estimate is conservative because FFT libraries do not expose every internal allocation. Metal reports unified host/device memory.

Return a conservative memory estimate for an existing phase-retrieval plan.

Reusable FFT plans and buffers for a uniformly-spaced reconstruction volume.

Reconstruct intensity into a preallocated (height, width, slices) array.

reconstruct(plan, wavefront, request)

Generate the requested volume and MinIP in one propagation pass. Access the outputs as result.volume and result.min_projection; an unrequested output is nothing. Set check_memory=false only when the conservative preflight should not stop allocation.

Allocate and return a reconstructed intensity volume using a reusable plan.

reconstruct_padded(plan, wavefront[, request]; mode=:mean)

Pad wavefront to the plan shape and reconstruct only the original central field of view. The propagation uses the padded plane, but no padded 3-D output volume is allocated.

Reconstruct complex amplitude into a preallocated volume.

Allocate and return the complex-amplitude reconstruction volume.

Compute the minimum-intensity projection along reconstruction depth.

Allocate and return the minimum-intensity projection over reconstruction depth.

Fill preallocated intensity volume and minimum-intensity projection.

Allocate and return both an intensity volume and its depth projection.

Propagate input into the preallocated output wavefront.

Allocate a wavefront and propagate input by one angular-spectrum step.

v0.2 keyword-compatible spelling of labonte.

Append one correspondence graph to an existing set of paths, preserving branches.

Apply an FFT-native low-pass filter in place to a wavefront.

Propagate input into the preallocated output wavefront.

Allocate a wavefront and propagate input by one angular-spectrum step.

Return the symbols of backends usable in the current process.

backend(kind; device=nothing)

Select and return the process-wide default execution backend. kind is :cpu, :cuda, :metal, or :auto. Subsequent calls that omit a backend use this selection. :auto prefers CUDA, then Metal, and always falls back to CPU.

Changing the default while concurrent tasks are running is unsupported. Pass an explicit backend object to each call when CPU and GPU work must coexist.

backend()

Return the process-wide default backend. A new Julia process starts with CPU. Call backend(:cpu), backend(:cuda), or backend(:metal) to change it. Explicit backend arguments remain available for side-by-side comparisons.

connected_component_labeling(image)

Label non-zero pixels using 8-way connectivity. The reference implementation runs on the host and returns consecutive UInt32 labels with zero reserved for the background. Device inputs are copied one image at a time.

Count non-background connected-component labels.

dictload(filename)

Load a particle dictionary from a file in JSON format. The dictionary should have UUID keys and values as Vector{Float32}, which includes the coordinates (and diameters) of the particles.

Arguments

• filename::String: The path to the file.

Returns

• Dict: The loaded dictionary.

dictsave(filename, dict)

Save a particle dictionary to a file in JSON format. The dictionary should have UUID keys and values as Vector{Float32}, which includes the coordinates (and diameters) of the particles.

Arguments

• filename::String: The path to the file.
• dict::Dict: The dictionary to save.

Returns

• nothing

dilate(volume)

Dilate each XY slice with a 3×3 neighbourhood. The operation stays on the input array's backend and preserves the v0.2 convention that boundary pixels remain false.

Remove duplicate, one-slice, highly elongated, and area-smaller-than-10 boxes.

find_external_contours(image)

Finds non-hole contours in binary images. This function is excuted on the CPU. Equivalent to CVRETREXTERNAL and CVCHAINAPPROX_NONE modes of the findContours() function provided in OpenCV.

Arguments

• image: The binary image. the image should be a 2D array of 0 and 1.

Returns

• Vector{Vector{CartesianIndex}}: A vector of contours. Each contour is a vector of CartesianIndex.

Return sorted, non-zero connected-component labels.

Create a complex Gabor wavefront from a non-negative intensity image.

Estimate the 12 quadratic distortion coefficients from a stereo image pair.

Return whether a backend is usable in the current Julia process.

labonte(frame1, frame2; kwargs...)

Apply the improved Labonté particle-correspondence algorithm to two frames. Input dictionaries are never mutated.

load_gray2float(path)

Load a grayscale image from a file and return it as a Array{Float32, 2} array.

Arguments

• path::String: The path to the image file.

Returns

• Array{Float32, 2}: The image as a Float32 array.

load_grayimg(path)

Load a grayscale image from a file and return it as a Array{Gray{N0f8}, 2} array.

Arguments

• path::String: The path to the image file.

Returns

• Array{Gray{N0f8}, 2}: The image as a Gray{N0f8} array.

make_background(pathlist; mode=:mode)

Make a background image from a list of image paths. The background image is calculated by taking the mean or mode of the images in the list. The default mode is :mode.

Arguments

• pathlist::Vector{String}: A list of image paths. glob() can be used to generate this list.
• mode::Symbol: The mode to use for calculating the background. Options are :mean or :mode. Default is :mode.

Returns

• Array{Float64, 2}: The background image.

make_background_mode(images; backend=backend())

Compute the per-pixel 8-bit mode without allocating the former 256 × height × width vote volume. GPU inputs are staged to the host once; this preprocessing step deliberately favours bounded memory over acceleration.

memory_diagnostic(backend, working_shape, request;
                  output_shape=working_shape, include_plan=true,
                  safety_factor=1.2)

Estimate new plan, output, and conversion allocations before reconstruction. The estimate is conservative because FFT libraries do not expose every internal allocation. Metal reports unified host/device memory.

Return a conservative memory estimate for an existing phase-retrieval plan.

Euclidean particle distance with a configurable optical-axis weight.

pad2d(input[, target_shape]; mode=:mean)

Centre input in a larger 2-D array. The default target is twice each input dimension. mode=:mean fills the border with the input mean; mode=:zero uses zero. The result stays on the input backend.

particle_bounding_boxes(binary_volume)

Connect slice components whenever their inclusive XY bounding boxes overlap. This keeps the original non-adjacent-z behaviour used to join fragmented holographic particle signatures.

Variant that joins a component only to a component in the preceding slice.

Calculate [x, y, z, equivalent_diameter] for each particle box.

Calculate [x, y, z] coordinates for detected particle bounding boxes.

phase_retrieval!(plan, hologram1, hologram2; iterations=10)

Run Gerchberg-Saxton phase retrieval using buffers owned by plan. The returned Wavefront aliases the plan workspace and is overwritten by the next call. Use phase_retrieval when an owning copy is required.

Run phase retrieval with plan and return an owning wavefront copy.

piv_map(backend, image1, image2; grid_size=128, interrogation_size=128, search_size=256)

Compute the same brute-force normalized-cross-correlation PIV map used in v0.2. CPU is the portable reference; CUDA.jl supplies the accelerated method. Metal currently uses the documented CPU fallback for this calibration step.

propagation_grid([backend], shape, wavelength, pixel_pitch)

Construct the distance-independent spatial-frequency grid used by the angular-spectrum method. shape may be a square side length or (height, width). All length parameters must use the same unit.

propagation_kernel([backend], distance, wavelength, grid)

Construct the angular-spectrum propagation multiplier for distance. The kernel is stored in the order consumed directly by plan_fft.

Apply the package's 12-coefficient quadratic camera-distortion mapping.

Reconstruct intensity into a preallocated (height, width, slices) array.

Allocate and return a reconstructed intensity volume using a reusable plan.

reconstruct(plan, wavefront, request)

Generate the requested volume and MinIP in one propagation pass. Access the outputs as result.volume and result.min_projection; an unrequested output is nothing. Set check_memory=false only when the conservative preflight should not stop allocation.

Fill preallocated intensity volume and minimum-intensity projection.

Allocate and return both an intensity volume and its depth projection.

Reconstruct complex amplitude into a preallocated volume.

Allocate and return the complex-amplitude reconstruction volume.

reconstruct_padded(plan, wavefront[, request]; mode=:mean)

Pad wavefront to the plan shape and reconstruct only the original central field of view. The propagation uses the padded plane, but no padded 3-D output volume is allocated.

Construct the rectangular angular-spectrum low-pass filter from Fugal (2009).

Construct the sixth-order super-Gaussian low-pass filter from Fugal (2009).

Wait for queued work on b to complete.

synchronize_backend(backend)

Wait for queued work on an execution backend. Use this before timing GPU work. The longer name avoids collisions with functions exported by CUDA.jl/Metal.jl.

Tamura focus coefficient (std / mean) with a stable all-zero case.

Copy x to b. An input already on b may be returned without copying.

Copy x to the currently selected backend().

Copy an array or wrapped optical value to host memory.

Merge a slice's rectangles into all prior XY-overlapping neighborhoods.

Merge rectangles only with neighborhoods present in the immediately prior slice.

Compute the minimum-intensity projection along reconstruction depth.

Allocate and return the minimum-intensity projection over reconstruction depth.