API Reference

create_shepp_logan_phantom(nx, ny, nz; fov=(20,20,20), ti=CTSheppLoganIntensities(), eltype=Float32)
create_shepp_logan_phantom(nx, ny, axis; fov=(20,20), slice_position=0.0, ti=CTSheppLoganIntensities(), eltype=Float32)

Generate a 3D Shepp-Logan phantom or a 2D slice of it.

For a 2D slice, provide nx, ny, and an axis (:axial, :coronal, :sagittal). The slice_position determines where the slice is taken. The intensities ti can be specified using CTSheppLoganIntensities() (default) or MRISheppLoganIntensities().

Parameters

• nx, ny, nz: Number of voxels in x, y, and z dimensions for 3D phantom; for 2D slice, nx and ny are used.
• fov: Tuple specifying the field of view in each dimension (default is (20, 20, 20) for 3D and (20, 20) for 2D).
• ti: Shepp-Logan intensities, defaulting to CTSheppLoganIntensities(), but accepts MRISheppLoganIntensities() or any custom SheppLoganIntensities struct.
• eltype: Data type for the phantom array (default is Float32).

CTSheppLoganIntensities()

Create a SheppLoganIntensities object with original CT version values.

Attribution

The intensities are fetched from the original paper [1].

References

[1] L. A. Shepp and B. F. Logan, “The Fourier reconstruction of a head section,” IEEE Trans. Nucl. Sci., vol. 21, no. 3, pp. 21–43, Jun. 1974, doi: 10.1109/TNS.1974.6499235.

MRISheppLoganIntensities()

Create a SheppLoganIntensities object with MRI (Toft's) version values.

Attribution

The intensities are from the PhD thesis of Peter Aundal Toft [1].

References

[1] P. A. Toft, “The Radon Transform - Theory and Implementation,” PhD Thesis, Technical University of Denmark, Kgs. Lyngby, Denmark, 1996. [Online]. Available: https://orbit.dtu.dk/files/5529668/Binder1.pdf

SheppLoganIntensities{T}

Struct to hold intensity values for the 12 ellipsoids in a 3D Shepp-Logan phantom. For 2D phantoms, only the first 10 values are typically used.

Fields:

• skull: Intensity of the skull.
• brain: Intensity of the brain.
• right_big: Intensity of the right big ellipsoid.
• left_big: Intensity of the left big ellipsoid.
• top: Intensity of the top ellipsoid.
• middle_high: Intensity of the middle high ellipsoid.
• bottom_left: Intensity of the bottom left ellipsoid.
• middle_low: Intensity of the middle low ellipsoid.
• bottom_center: Intensity of the bottom center ellipsoid.
• bottom_right: Intensity of the bottom right ellipsoid.
• extra_1: Intensity of the extra 1 ellipsoid.
• extra_2: Intensity of the extra 2 ellipsoid.

Note: All intensities are additive values, so the total intensity at a given point is the sum of the intensities of all ellipsoids that contain that point.

SheppLoganMask(; kwargs...)

Create a SheppLoganIntensities{Bool} object for masking specific ellipsoids. Defaults to all false. Use keyword arguments to set specific ellipsoids to true.

create_torso_phantom(nx::Int, ny::Int, nz::Int; fov=(30, 30, 30), respiratory_signal=nothing, cardiac_volumes=nothing, ti::AbstractTissueParameters=TissueIntensities(), eltype=Float32) -> Array{eltype, 4}
create_torso_phantom(nx::Int, ny::Int, axis::Symbol; fov=(30, 30), slice_position=0.0, eltype=Float32) -> Array{eltype, 3}

Generate a 3D torso phantom with anatomical structures including torso outline, lungs, heart, and vessels.

Arguments

• nx::Int=128: Number of voxels in x-direction
• ny::Int=128: Number of voxels in y-direction
• nz::Int=128: Number of voxels in z-direction (ignored for 2D slice generation)
• axis::Symbol: Slice orientation for 2D phantom - :axial, :coronal, or :sagittal (ignored for 3D phantom)

Keywords

• fov::Tuple=(30, 30, 30): Field of view in cm for (x, y, z) directions for 3D phantom; for 2D phantom, only first two elements are used
• slice_position::Real=0.0: Position of the slice in cm (in the third dimension) for 2D phantom generation; ignored for 3D phantom
• respiratory_signal::Union{Nothing,AbstractVector}=nothing: Respiratory signal in liters for 4D phantom generation
• cardiac_volumes::Union{Nothing,NamedTuple}=nothing: Cardiac volumes in mL for 4D phantom generation; must have fields :lv, :rv, :la, :ra
• ti::AbstractTissueParameters=TissueIntensities(): Tissue parameters (TissueIntensities or TissueMask) for different structures
• eltype=Float32: Element type for the generated phantom array (Float32, Float64, ComplexF32, ComplexF64, etc.). When TissueMask is passed, returns BitArray regardless of eltype.

Returns

• Array{eltype, 4}: 4D phantom array with size (nx, ny, nz, nt) where nt is the number of time frames. Returns BitArray when TissueMask is passed.
• Array{eltype, 3}: 3D phantom array with size (nx, ny, nz) for static phantom or 2D slice array with size (nx, ny) for 2D phantom generation.

Description

Creates a simplified anatomical torso phantom with the following structures:

• Torso: Multi-segment outer boundary (upper/middle/lower) for realistic shape
• Lungs: Multiple ellipsoids representing left/right lung lobes
• Heart: Multiple ellipsoids for ventricles and atria
• Vessels: Aorta, pulmonary artery, and superior vena cava
• Spine: Vertebral column with 12 vertebrae
• Ribs: Paired rib structures arranged in 9 levels
• Liver and Stomach: Basic ellipsoidal shapes in the abdomen

Example

phantom = create_torso_phantom(128, 128, 128)  # Float32
phantom_f64 = create_torso_phantom(128, 128, 128; eltype=Float64)
phantom_complex = create_torso_phantom(128, 128, 128; eltype=ComplexF32)

# Create binary mask for lung tissue
lung_mask = TissueMask(lung=true)
phantom_mask = create_torso_phantom(128, 128, 128; ti=lung_mask)  # BitArray

TissueIntensities <: AbstractTissueParameters

Struct to hold tissue intensity values for different anatomical structures in the torso phantom.

Fields:

• lung::Float64: Intensity value for lung tissue
• heart::Float64: Intensity value for heart muscle
• vessels_blood::Float64: Intensity value for blood in vessels
• bones::Float64: Intensity value for bone tissue
• liver::Float64: Intensity value for liver tissue
• stomach::Float64: Intensity value for stomach tissue
• body::Float64: Intensity value for general body tissue
• lv_blood::Float64: Intensity value for left ventricle blood
• rv_blood::Float64: Intensity value for right ventricle blood
• la_blood::Float64: Intensity value for left atrium blood
• ra_blood::Float64: Intensity value for right atrium blood

TissueMask <: AbstractTissueParameters

Struct to hold tissue mask specification for binary phantom generation. Only one tissue type should be selected (set to true), all others should be false.

Fields:

• lung::Bool: Whether to include lung tissue
• heart::Bool: Whether to include heart muscle
• vessels_blood::Bool: Whether to include blood in vessels
• bones::Bool: Whether to include bone tissue
• liver::Bool: Whether to include liver tissue
• stomach::Bool: Whether to include stomach tissue
• body::Bool: Whether to include general body tissue
• lv_blood::Bool: Whether to include left ventricle blood
• rv_blood::Bool: Whether to include right ventricle blood
• la_blood::Bool: Whether to include left atrium blood
• ra_blood::Bool: Whether to include right atrium blood

Example

# Create a mask for lung tissue only
lung_mask = TissueMask(lung=true)

# Create a mask for heart muscle only
heart_mask = TissueMask(heart=true)

RespiratoryPhysiology

Physiology constants controlling simulated respiratory signal (liters).

Fields

• minL, maxL: Minimum and maximum lung volume in liters
• asym_amp: Amplitude of asymmetry harmonic (fraction of main amplitude)
• amp_mod_amp, amp_mod_freq: Amplitude modulation amplitude (fraction) and frequency (Hz)
• rr_var_amp, rr_var_freq: Respiratory rate variability amplitude (fraction of base) and frequency (Hz)

Usage Create with keyword overrides and pass as physiology to generate_respiratory_signal.

generate_respiratory_signal(duration=60.0, fs=50.0, rr=15.0; physiology::RespiratoryPhysiology=RespiratoryPhysiology()) -> (Vector{Float64}, Vector{Float64})

Generate a simplified respiratory signal in liters.

Arguments

• duration::Float64=60.0: Duration of signal in seconds
• fs::Float64=50.0: Sampling frequency in Hz
• rr::Float64=15.0: Respiratory rate in breaths per minute
• physiology::RespiratoryPhysiology=RespiratoryPhysiology(): Optional physiology constants

Returns

• Tuple of (timevector, respiratorysignal_liters)

Description

Generates a synthetic respiratory signal with:

• Sinusoidal breathing pattern
• Asymmetric inspiration/expiration
• Amplitude modulation (breathing depth variation)

Example

t, resp_L = generate_respiratory_signal(60.0, 50.0, 15.0)
# resp_L is in liters

CardiacPhysiology

Physiology constants controlling simulated cardiac chamber volumes (mL) and slow modulations.

Fields

• lv_edv: Left ventricle end-diastolic volume (mL)
• lv_esv: Left ventricle end-systolic volume (mL)
• rv_edv: Right ventricle end-diastolic volume (mL)
• rv_esv: Right ventricle end-systolic volume (mL)
• la_min, la_max: Left atrium min/max volumes (mL)
• ra_min, ra_max: Right atrium min/max volumes (mL)
• hr_var_amp, hr_var_freq: Heart rate variability amplitude (fraction) and frequency (Hz)
• v_amp_amp, v_amp_freq: Ventricular amplitude modulation amplitude (fraction) and frequency (Hz)
• a_amp_amp, a_amp_freq: Atrial amplitude modulation amplitude (fraction) and frequency (Hz)
• bw_amp, bw_freq: Baseline wander amplitude (mL) and frequency (Hz)
• s_frac_base: Base systole fraction (0..1)
• lv_kick_amp_frac, lv_kick_center, lv_kick_width: Left ventricle atrial kick amplitude fraction, center, and width
• rv_kick_amp_frac, rv_kick_center, rv_kick_width: Right ventricle atrial kick amplitude fraction, center, and width
• la_contr_amp_frac, la_contr_center, la_contr_width: Left atrium contraction amplitude fraction, center, and width
• ra_contr_amp_frac, ra_contr_center, ra_contr_width: Right atrium contraction amplitude fraction, center, and width

Usage Create with keyword overrides and pass as physiology to generate_cardiac_signals to customize volumes and modulations.

Example

phys = CardiacPhysiology(lv_edv=130.0, lv_esv=55.0, rv_edv=140.0, rv_esv=65.0)
t, vols = generate_cardiac_signals(10.0, 500.0, 70.0; physiology=phys)

generate_cardiac_signals(duration=10.0, fs=500.0, hr=70.0; physiology::CardiacPhysiology=CardiacPhysiology()) -> (Vector{Float64}, NamedTuple)

Simulate cardiac chamber volumes (mL) for left/right ventricles and atria.

Arguments

• duration::Float64=10.0: Duration of signal in seconds
• fs::Float64=500.0: Sampling frequency in Hz
• hr::Float64=70.0: Heart rate in beats per minute
• physiology::CardiacPhysiology=CardiacPhysiology(): Optional physiology constants

Returns

• Tuple of (time_vector, volumes::NamedTuple{(:lv,:rv,:la,:ra)}) where each field is Vector{Float64}

Description

• Generates four periodic time series of chamber volumes in milliliters.
• The ventricles are high during diastole and low during systole; atria are approximately in opposite phase.
• Default physiology constants are set to plausible values but can be tuned via physiology.
• It includes slight heart rate variability, amplitude modulation, and baseline wander.

Example

t, vols = generate_cardiac_signals(10.0, 500.0, 70.0)
# vols.lv, vols.rv, vols.la, vols.ra are in mL

create_tubes_phantom(nx::Int, ny::Int, nz::Int; kwargs...)
create_tubes_phantom(nx::Int, ny::Int, axis::Symbol; kwargs...)

Generate a tubes phantom. When invoked with three dimensions, a 3D volume is returned; when invoked with an axis symbol, a 2D slice is produced. In both modes the ti keyword accepts either a single TubesIntensities or a vector of intensities to render a stack of frames (resulting in a 4D volume or 3D stack, respectively).

Arguments

• nx::Int: Number of voxels in the x direction
• ny::Int: Number of voxels in the y direction
• nz::Int: Number of voxels in the z direction (only for volume mode)
• axis::Symbol: Slice orientation (:axial, :coronal, or :sagittal)

Keyword Arguments

• fov::Tuple{Real,Real,Real}: Field of view in cm for volume mode (default: (10.0, 10.0, 10.0))
• fov::Tuple{Real,Real}: Field of view in cm for slice mode (default: (10.0, 10.0))
• slice_position::Real: Position along the perpendicular axis in cm (default: 0.0, slice mode only)
• tg::TubesGeometry: Geometry parameters (default: TubesGeometry())
• ti::Union{TubesIntensities, Vector{<:TubesIntensities}}: Either a single intensity set or a collection of intensity sets to produce multiple frames (default: TubesIntensities())
• eltype::Type: Element type for the phantom array (default: Float32)

Returns

• Volume mode: Array{eltype,3} for single intensity or Array{eltype,4} when a vector of intensities is provided
• Slice mode: Array{eltype,2} for single intensity or Array{eltype,3} when multiple intensities are passed

Examples

phantom3d = create_tubes_phantom(128, 128, 128)
phantom_stack = create_tubes_phantom(128, 128, 128; ti=[TubesIntensities(), TubesIntensities(tube_fillings=[0.2])])
phantom_axial = create_tubes_phantom(128, 128, :axial; slice_position=2.0)
phantom_axial_stack = create_tubes_phantom(128, 128, :axial; ti=[TubesIntensities(), TubesIntensities(tube_fillings=[0.8])])

TubesGeometry

Geometry parameters for the tubes phantom.

Fields

• outer_radius::Float64: Radius of the outer cylinder
• outer_height::Float64: Height of the outer cylinder
• tube_wall_thickness::Float64: Thickness of tube walls
• gap_fraction::Float64: Fraction of space between tubes

TubesIntensities

Intensity parameters for the tubes phantom.

Fields

• outer_cylinder::Float64: Intensity of the outer cylinder (default: 0.25)
• tube_wall::Float64: Intensity of tube walls (default: 0.0)
• tube_fillings::Vector{Float64}: Intensities for tube fillings (default: [0.1, 0.3, 0.5, 0.7, 0.9, 1.0])

TubesMask(; kwargs...)

Create a boolean mask for the tubes phantom.

Example

mask = TubesMask(outer_cylinder=true, tube_wall=false, tube_fillings=[true, true, true, true, true, true])

Ellipsoid

Struct to store the parameters of an ellipsoid.

The points (x, y, z) inside the ellipsoid satisfy the equation: $(\frac{|x - cx|}{rx})^2 + (\frac{|y - cy|}{ry})^2 + (\frac{|z - cz|}{rz})^2 \leq 1$

Fields:

• cx::Real: X-coordinate of the center
• cy::Real: Y-coordinate of the center
• cz::Real: Z-coordinate of the center
• rx::Real: Radius in x-direction
• ry::Real: Radius in y-direction
• rz::Real: Radius in z-direction
• intensity::Real: Intensity value for the ellipsoid

SuperEllipsoid

Struct to store the parameters of a superellipsoid.

The points (x, y, z) inside the superellipsoid satisfy the equation:

``(\frac{|x - cx|}{rx})^{ex[1]} + (\frac{|y - cy|}{ry})^{ex[2]} + (\frac{|z - cz|}{rz})^{ex[3]} \leq 1``

Fields:

• cx::Real: X-coordinate of the center
• cy::Real: Y-coordinate of the center
• cz::Real: Z-coordinate of the center
• rx::Real: Radius in x-direction
• ry::Real: Radius in y-direction
• rz::Real: Radius in z-direction
• ex::NTuple{3,Real}: Exponents for (x, y, z) directions
• intensity::Real: Intensity value for the superellipsoid

RotatedEllipsoid

Struct to store the parameters of a rotated ellipsoid.

The points (x, y, z) inside the ellipsoid satisfy the equation: $(R^{-1} (P - C))^T D (R^{-1} (P - C)) \leq 1$ where R is the rotation matrix (Z-Y-X order), C is the center, and D is the diagonal matrix of inverse radii squared.

Fields:

• cx, cy, cz::Real: Center coordinates
• rx, ry, rz::Real: Radii
• phi, theta, psi::Real: Rotation angles in radians (Z-Y-X order)
• intensity::Real: Intensity value

CylinderX

Struct to store the parameters of a cylinder aligned along the x-axis.

A cylinder is defined by its center (cx, cy, cz), radius, and height. The cylinder is aligned along the x-axis and extends from cx - height/2 to cx + height/2.

The points (x, y, z) inside the cylinder satisfy the inequalities: $\sqrt{(y - cy)^2 + (z - cz)^2} \leq r$ and $|x - cx| \leq \text{height}/2$

Fields:

• cx::Real: X-coordinate of the center
• cy::Real: Y-coordinate of the center
• cz::Real: Z-coordinate of the center
• r::Real: Radius of the cylinder
• height::Real: Height of the cylinder along the x-axis
• intensity::Real: Intensity value for the cylinder

CylinderY

Struct to store the parameters of a cylinder aligned along the y-axis.

A cylinder is defined by its center (cx, cy, cz), radius, and height. The cylinder is aligned along the y-axis and extends from cy - height/2 to cy + height/2.

The points (x, y, z) inside the cylinder satisfy the inequalities: $\sqrt{(x - cx)^2 + (z - cz)^2} \leq r$ and $|y - cy| \leq \text{height}/2$

Fields:

• cx::Real: X-coordinate of the center
• cy::Real: Y-coordinate of the center
• cz::Real: Z-coordinate of the center
• r::Real: Radius of the cylinder
• height::Real: Height of the cylinder along the y-axis
• intensity::Real: Intensity value for the cylinder

CylinderZ

Struct to store the parameters of a cylinder aligned along the z-axis.

A cylinder is defined by its center (cx, cy, cz), radius, and height. The cylinder is aligned along the z-axis and extends from cz - height/2 to cz + height/2.

The points (x, y, z) inside the cylinder satisfy the inequalities: $\sqrt{(x - cx)^2 + (y - cy)^2} \leq r$ and $|z - cz| \leq \text{height}/2$

Fields:

• cx::Real: X-coordinate of the center
• cy::Real: Y-coordinate of the center
• cz::Real: Z-coordinate of the center
• r::Real: Radius of the cylinder
• height::Real: Height of the cylinder along the z-axis
• intensity::Real: Intensity value for the cylinder