xdesign.phantom

Objects and methods for computing the quality of reconstructions.

Module author: Daniel J Ching <carterbox@users.noreply.github.com>

Phantoms

Defines an object for simulating X-ray phantoms.

Module author: Daniel J Ching <carterbox@users.noreply.github.com>

Phantom([geometry, children, material])

An object for the purpose of evaluating X-ray imaging methods.

save_phantom(phantom, filename)

Save phantom to file as a python repr.

load_phantom(filename)

Load phantom from file containing a python repr.

pickle_phantom(phantom, filename)

Save phantom to file as a python pickle.

unpickle_phantom(filename)

Load phantom from file as a python pickle.
class xdesign.phantom.phantom.Phantom(geometry=None, children=[], material=None)[source]

Bases: object

An object for the purpose of evaluating X-ray imaging methods.

Phantoms may be hierarchical structures with children that are contained within and/or a parent which contains them. They have two parts: a geometry and properties. The geometry defines the spatial extent over which the properties are valid. Properties are parameters which a Probe uses to measure the Phantom.

All Phantoms must fit within the geometry of their ancestors. Phantoms whose geometry is None act as containers.

geometry

The spatial boundary of the Phantom; may be None.

Type

Entity

children

A list of Phantoms contained in this Phantom.

parent

The Phantom containing this Phantom.

material

The mass_attenuation of the phantom.

population

The number of decendents of this phantom.

append(child)[source]

Add a child to the Phantom.

Only add the child if it is contained within the geometry of its ancestors.

property center

Return the centroid of the Phantom.

property density

Return the geometric density of the Phantom.

property geometry

Return the geometry of the Phantom.

property is_leaf

Return whether the Phantom is a leaf node.

pop(i=- 1)[source]

Pop the i-th child from the Phantom.

property radius

Return the radius of the smallest boundary sphere.

rotate(theta, point=Point([]), axis=None)[source]

Rotate around an axis that passes through the given point.

sprinkle(counts, radius, gap=0, region=None, material=None, max_density=1, shape=<class 'xdesign.geometry.area.Circle'>)[source]

Sprinkle a number of Circle shaped Phantoms around the Phantom. Uses various termination criteria to determine when to stop trying to add circles.

Parameters

  • counts (int) – The number of circles to be added.

  • radius (scalar or list) – The radius of the circles to be added.

  • gap (float, optional) – The minimum distance between circle boundaries. A negative value allows overlapping edges.

  • region (Entity, optional) – The new circles are confined to this shape. None if the circles are allowed anywhere.

  • max_density (scalar, optional) – Stops adding circles when the geometric density of the phantom reaches this ratio.

  • material (scalar, optional) – A mass attenuation parameter passed to the circles.

Returns

counts (scalar) – The number of circles successfully added.

translate(vector)[source]

Translate the Phantom.

property volume

Return the volume of the Phantom

xdesign.phantom.phantom.load_phantom(filename)[source]

Load phantom from file containing a python repr.

xdesign.phantom.phantom.pickle_phantom(phantom, filename)[source]

Save phantom to file as a python pickle.

xdesign.phantom.phantom.save_phantom(phantom, filename)[source]

Save phantom to file as a python repr.

xdesign.phantom.phantom.unpickle_phantom(filename)[source]

Load phantom from file as a python pickle.

Standard phantoms

Defines an object for simulating X-ray phantoms.

Module author: Daniel J Ching <carterbox@users.noreply.github.com>

XDesignDefault()

Generates a Phantom for internal testing of XDesign.

HyperbolicConcentric([min_width, exponent])

Generates a series of cocentric alternating black and white circles whose radii are changing at a parabolic rate.

DynamicRange([steps, jitter, geometry])

Generates a phantom of randomly placed circles for determining dynamic range.

DogaCircles([n_sizes, size_ratio, n_shuffles])

Rows of increasingly smaller circles.

SlantedSquares([count, angle, gap])

Generates a collection of slanted squares.

UnitCircle([radius, material])

Generates a phantom with a single circle in its center.

SiemensStar([n_sectors, center, radius])

Generates a Siemens star.
class xdesign.phantom.standards.DogaCircles(n_sizes=5, size_ratio=0.5, n_shuffles=5)[source]

Bases: xdesign.phantom.phantom.Phantom

Rows of increasingly smaller circles. Initally arranged in an ordered Latin square, the inital arrangement can be randomly shuffled.

radii

radii of circles

Type

ndarray

x

x position of circles

Type

ndarray

y

y position of circles

Type

ndarray

class xdesign.phantom.standards.DynamicRange(steps=10, jitter=True, geometry=Rectangle(<MagicMock name='mock()' id='140346947267856'>, <MagicMock name='mock().tolist()' id='140346817705296'>))[source]

Bases: xdesign.phantom.phantom.Phantom

Generates a phantom of randomly placed circles for determining dynamic range.

Parameters

  • steps (scalar, optional) – The orders of magnitude (base 2) that the colors of the circles cover.

  • jitter (bool, optional) – True : circles are placed in a jittered grid False : circles are randomly placed

  • shape (string, optional)

class xdesign.phantom.standards.HyperbolicConcentric(min_width=0.1, exponent=0.5)[source]

Bases: xdesign.phantom.phantom.Phantom

Generates a series of cocentric alternating black and white circles whose radii are changing at a parabolic rate. These line spacings cover a range of scales and can be used to estimate the Modulation Transfer Function. The radii change according to this function: r(n) = r0*(n+1)^k.

radii

The list of radii of the circles

Type

list

widths

The list of the widths of the bands

Type

list

class xdesign.phantom.standards.SiemensStar(n_sectors=4, center=Point([]), radius=0.5)[source]

Bases: xdesign.phantom.phantom.Phantom

Generates a Siemens star.

ratio

The spatial frequency times the proportional radius. e.g to get the frequency, f, divide this ratio by some fraction of the maximum radius: f = ratio/radius_fraction

Type

scalar

class xdesign.phantom.standards.SlantedSquares(count=10, angle=0.08726646259972222, gap=0)[source]

Bases: xdesign.phantom.phantom.Phantom

Generates a collection of slanted squares. Squares are arranged in concentric circles such that the space between squares is at least gap. The size of the squares is adaptive such that they all remain within the unit circle.

angle

the angle of slant in radians

Type

scalar

count

the total number of squares

Type

scalar

gap

the minimum space between squares

Type

scalar

side_length

the size of the squares

Type

scalar

squares_per_level

the number of squares at each level

Type

list

radius_per_level

the radius at each level

Type

list

n_levels

the number of levels

Type

scalar

class xdesign.phantom.standards.UnitCircle(radius=0.5, material=SimpleMaterial(mass_attenuation=1.0))[source]

Bases: xdesign.phantom.phantom.Phantom

Generates a phantom with a single circle in its center.

class xdesign.phantom.standards.XDesignDefault[source]

Bases: xdesign.phantom.phantom.Phantom

Generates a Phantom for internal testing of XDesign.

The default phantom is: (1) nested, it contains phantoms within phantoms; (2) geometrically simple, the sinogram can be verified visually; and (3) representative, it contains the three main geometric elements: circle, polygon, and mesh.

Custom phantoms

Defines an object for simulating X-ray phantoms.

Module author: Daniel J Ching <carterbox@users.noreply.github.com>

Soil([porosity])

Generates a phantom with structure similar to soil.

WetCircles()

Foam([size_range, gap, porosity])

Generates a phantom with structure similar to foam.

Softwood()

Generate a Phantom with structure similar to wood.
class xdesign.phantom.custom.Foam(size_range=[0.05, 0.01], gap=0, porosity=1)[source]

Bases: xdesign.phantom.standards.UnitCircle

Generates a phantom with structure similar to foam.

class xdesign.phantom.custom.Softwood[source]

Bases: xdesign.phantom.phantom.Phantom

Generate a Phantom with structure similar to wood.

Parameters

  • ringsize (float [cm]) – The thickness of the annual rings in cm.

  • latewood_fraction (float) – The volume ratio of latewood cells to earlywood cells

  • ray_fraction (float) – The ratio of rows of ray cells to rows of tracheids

  • ray_height (float [cm]) – The height of the ray cells

  • cell_width, cell_height (float [cm]) – The shape of the earlywood cells

  • cell_thickness (float [cm]) – The thickness of the earlywood cell walls

  • frame (arraylike [cm]) – A bounding box for the cells

class xdesign.phantom.custom.Soil(porosity=0.412)[source]

Bases: xdesign.phantom.standards.UnitCircle

Generates a phantom with structure similar to soil.

References

Schlüter, S., Sheppard, A., Brown, K., & Wildenschild, D. (2014). Image processing of multiphase images obtained via X‐ray microtomography: a review. Water Resources Research, 50(4), 3615-3639.

class xdesign.phantom.custom.WetCircles[source]

Bases: xdesign.phantom.standards.UnitCircle