Tube

Handles the tubular objects created in AirQuant.

graph A[handle] --> C(AirQuant) B[matlab.mixin.SetGet] --> C C --> D[Tube] C --> E[Network] D --> F[Airway] E --> G[ClinicalAirways] H[library] I[SuperMeasure] --> J[AirwayFWHMesl] L[AQEllipse]

Contents

tube.Tube
tube.Airway

tube.Tube

class tube.Tube(network, skelpoints, ID)

Bases: library.AirQuant, matlab.mixin.SetGet

A tubular structure in a connected tree-like structure.

Represents a tube based on some source image for analysis. Where quantitative metrics can be extracted.

Parameters

source (float) – INHERITED array of interpolated perpendicular slice patches of source along the tube.Tube.spline.
seg (float) – INHERITED array of interpolated perpendicular slice patches of seg along the tube.Tube.spline.
voxdim (float) – INHERITED triplet that specifies the dimensions of the tube source where the third dimension represents the tube.Tube.spline interval.
parent (tube.Tube) – vector of parent tubes to this tube.
children (tube.Tube) – vector of child tubes to this tube.
generation (int) – scalar, number of ancestor tubes.
network (network.TubeNetwork) – tube network object that this tube is a subset.
skelpoints (int) – vector of linear indexed points that make up the tube’s centreline
spline (struct) – polynomial spline that is created using cscvn.
patchprop (struct) – property per tube patch slice given as list e.g patchprop.arcpoints
prunelength (float) – two element vector that represents in units of patchprop.arclength how much of the tube to prune at either end. This is set by tube.Tube.SetPruneLength()
stats (struct) – stats property for current tube e.g stats.arclength
region (struct) – region that this tube belongs to e.g. region.lobe
ID (int) – PROTECTED scalar index assigned to tube.
method (char) – PROTECTED method used to make in-slice measurements e.g. tube.Tube.diameters
diameters (float) – PROTECTED m x n array of diameter measurements made in plane. where m is the number of interpolated slices and n is the number of in-plane measurements.
areas (float) – PROTECTED m x n array of area measurements made in plane. where m is the number of interpolated slices and n is the number of in-plane measurements.
volumes (float) – PROTECTED vector of volume measurements, where length is the number of in-plane measurements.

Warning

Though it is possible to set multiple parents, some functionality will be lost. e.g. it is not possible to use tube.Tube.SetGeneration()

Todo

make tubes saveable and loadable and that these operations can be done independently of the network object.
decouple from network. i.e. remove network as property, and convert skelpoints to sub index.

Ancestors(): returns parents of parent tubes inclusive.

ApproxSegDiameter(sourcepoint)

Gets the approximate diameter using the segmentation for a given point.

Uses the distance transform of tube.Tube.network.seg: to get the approximate diameter of the segmentation at a given point.

Todo

consider diameter conversion to mm

Parameters: sourcepoint (int,triplet) – subindex coordinates of the point to sample.
Returns: 1 variable * segdiameter(float): segmentation diameter in pixels.

ComputeArcLength()

Computes arclength of the tube.

Computes arc length of the tube by considering the total length of the tube spline and saves to tube.Tube.stats.arclength.

ComputeChangeAngle()

Compute the change in angle this tube.

Compute the change in between the leading direction to the trailing direction of this tube.

Returns: 1 variables * change_deg(scalar) = angle in degrees.

ComputeDirections()

Compute the leading and trailing directions of the tube.

Using the beginning and end section of the tube, calculates the leading and trailing direction vectors respectively.

Returns: 2 variables * lead_dir(3x1 vector) = vector of leading direction. * trail_dir(3x1 vector) = vector of trailing direction.

ComputeEucLength()

Computes euclidean length of the tube.

Computes euclidean length of the tube by considering the skeleton endpoints and saves to tube.Tube.stats.euclength

ComputeGradient()

Computes the gradient value of the tube.

the gradient is the % gradient of tapering in diameter along the length of the tube. It is calculated by using a bisquare linear fitting to fit the line \(y=mx+c\) to measurements. and then taking gradient coefficient of the result. The result is saved in tube.Tube.stats.gradient.

\[gradient = -m\]

Returns: 1 variable * gradientval (array) gradient value of each ring.

ComputeIntertaper(trim, parentfail)

Computes the intertaper value.

intertaper value is the % change in mean diameter of the tube relative to the parent tube’s mean diameter. The result is saved in tube.Tube.stats.intertaper.

\[intertaper = \hat{d}_{p} - d / \hat{d}_{p}\]

Args: trim(float): OPTIONAL default = 0 trim as % of extremes

of data to discard in trimmean calculation.

parentfail: OPTIONAL default = false require lack of: parent measurement to raise error.

Returns: 1 variable * intertaper (array) intertaper value of each ring.

ComputeIntrataper()

Computes the intrataper value.

Intrataper is the % of tapering in diameter along the length of the tube. It is calculated by using a bisquare linear fitting to fit the line \(y=mx+c\) to measurements. Then computing the ratio of the coefficients. The result is saved in `tube.Tube.stats`intrataper.

\[intrataper = - m / c\]

Returns: 1 variable * intrataperval (array) intrataper value of each ring.

ComputeMeanArea(trim)

Computes the mean area of each measurement type in tube.Tube.areas.

Where tube.Tube.areas is a m x n matrix, the mean is calculated for each m row returning an n length vector. result is saved in tube.Tube.stats.meanarea and tube.Tube.stats.meanarea_trim.

Parameters: trim (float) – OPTIONAL default = 0 trim as % of extremes of data to discard in trimmean calculation.
Returns: 1 variable * meanAval (array) mean value of each ring.

ComputeMeanDiameter(trim)

Computes the trim mean diameter of each measurement type in tube.Tube.diameters.

Where tube.Tube.diameters is a m x n matrix, the trimmean is calculated for each m row returning an n length vector. result is saved in tube.Tube.stats.trimmean and tube.Tube.stats.trimmean_trim. For ordinary mean (no trim) set trim to 0.

Parameters

trim (float) – OPTIONAL default = 0 trim as % of extremes
calculation. (of data to discard in trimmean) –

ComputeMeanHydraulicD(trim)

Computes the trim mean hydraulic diameter of each measurement type in tube.Tube.patchprop.hydraulic_diameter.

Where tube.Tube.patchprop.hydraulic_diameter is a m x n matrix, the trimmean is calculated for each m row returning an n length vector. result is saved in tube.Tube.stats.hydraulicD_mean and tube.Tube.stats.hydraulicD_trim. For ordinary mean (no trim) set trim to 0.

Parameters

trim (float) – OPTIONAL default = 0 trim as % of extremes
calculation. (of data to discard in trimmean) –

ComputeParentAngle()

Compute the angle of the parent to this tube.

Compute the angle of the parent trailing direction to the leading direction of this tube. If this tube has no parent then the output will be NaN.

Returns: 1 variables * parent_deg(scalar) = angle in degrees. NaN if no parent.

ComputeSiblingAngle(overwrite)

Compute the angle of this tube to its sibling (bifurcation only).

Computes the leading angle of this tube to the leading direction of its sibling. If this tube has multiple siblings then the output will be NaN.

Parameters

overwrite (bool) –
behaviour (value has already been set then completes. This) –
efficiency. (has been added for) –

Returns

1 variables * sibling_deg(scalar) = angle in degrees. NaN if multiple

siblings.

ComputeTortuosity()

Computes tortuosity of the tube.

Computes tortuosity of the tube by considering the ratio of the arc:euclidean length and saves to tube.Tube.stats.tortuosity.

ComputeVolume()

Computes volume.

The volume is calculated as an integration of the areas against its arclength by trapezium numerical approximation. The result is saved in tube.Tube.stats.volume.

Returns: 1 variable * volumeval (array) volume value of each ring.

Descendants(): returns children of children tubes in a breadth-first search list inclusive.

ExportCSV(filename)

Export tube properties and measurements to csv file.

A list of properties from patchprop and measurements from diameters and areas saved into a single csv file where each slice is represented by a row.

Todo

showcase example

Parameters: path (char) – filename to save as.

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).ExportCSV('example_tube');

ExportOrthoPatches(path, casename)

export perpendicular slice patches of this tube.

export the perpendicular slice patches of this tube stored in source as int16 tiff files.

Parameters

path (str) – path to directory to save the exported patches. The directory will be created if it doesn’t already exist.
casename (char) – casename to use as prefix to each patch slice name.

Example

>>> run CA_base.m;
>>> AQnet.tubes(98).ExportOrthoPatches('patches','example')

FindSplinePoints(options)

find equidistant points at some given interval along the length of the spline.

Integrates along the discontinuous portions of the spline at the chosen interval to save equidistant parametrized points. This is necessary for a continous sampling along the spline otherwise there is no spatial understanding of how often we are resampling a tube. e.g. curved parts could end up being sampled more. Also calls tube.Tube.ComputeTortuosity().

Parameters

options.sample_interval (float) –

OPTIONAL default = `:attr:`network.TubeNetwork.spline_sample_sz.

The interval size along which to interpolate the spline.

GetSibling()

Get siblings of tube if they exist.

Returns

1 variable. * siblings(vector of tube) = returns vector of tubes. If

no parent or no siblings then returns empty.

I2S(I): Fast specific implementation of MATLAB’s ind2sub.

MakePatchSlices(vol, options)

Interpolates perpendicular slices as if travelling along the tube spline.

Interpolates perpendicular slices along the spline at tube.Tube.patchprop.arcpoints. i.e. the spline interval as found by tube.Tube.FindSplinePoints() and saves them to tube.Tube.source.

Note

This function will use the GPU if available only when :param:`options.method` = ‘linear’ and the parallel copmputing toolbox is installed.

Todo

Heavily reliant on the network class structure.
Consider decoupling network in this function.
Consider incorporating matlabs obliqueslice function.

Parameters

vol (float) – must be three dimensional image
options.type (char) – OPTIONAL default = ‘infer’, must be either {‘source’,’seg’,’infer’}. What type is :param:`vol`.
options.usesegcrop (logical) – OPTIONAL default = false use dynamic slicing, vary the size of the plane dependant on tube.Tube.network.seg size at that point.
options.method (char) – OPTIONAL default = ‘cubic’ see interp3 for details.
= (options.sample_sz = OPTIOPNAL `default) –
obj.network.plane_sample_sz`. interpolation pixel size.

MakeSpline(options)

fits a spline to the centreline of the tube.

Using the object property tube.Tube.skelpoints, a polynomial spline is fit to this list of points. A moving average is used to smooth the skeletal points, it can also use the parent tube to initialise this moving average. For a better understanding of the spline output see cscvn.

Parameters: useparent (bool) – OPTIONAL default = true uses the parent tube skel points if available to initialise the moving average.

Measure(classmethod, varargin)

Call desired method to make measurement on the interpolated tube patch slices.

This calls a subclass of measure.SuperMeasure to make measurement on the interpolated patch slices of the tube. The measure type called must be specific to the tube type. e.g. airway for airway images. Also recomputes all measurements.

Todo

add more detailed documentation to this function.
make measurements specific page to link to.
initiate by deleting all calculations.

Parameters

classmethod (char) – Name of class method to make measurement.
varargin –

OrthoView(options)

View a series of patches of tube slices as a volume image stack using MATLAB’s inbuilt othogonal 3d viewer.

Todo

add 4th panel to show plot
make scrollable by mousewheel
link to orthosliceviewer

Parameters

type (char) – OPTIONAL `default = ‘source’ object property that is a 3D array to view.
rings (bool array) – OPTIONAL default = ones(1,size(:attr:`measures,1))` same length as number of measures per patch, i.e. number of rings. For each ring to visualise. All rings by default.
ellipses (bool) – OPTIONAL default = true to view ellipses of measure if available.
points (bool) – OPTIONAL default = true to view points of measure if available.

Returns

1 variable * s(orthosliceViewer): handle to created graphics

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).OrthoView();

ParseVolOut(options)

Parse volume of a given property name

See AirQuant.AirQuantParseVolOut().

Plot3(color)

plot this tube as a line as if an edge on a 3D network graph.

Note that datatips in plot contains specific information.

Parameters: color – OPTIONAL default = ‘k’ color of line. Can be any MATLAB accepted color format, e.g. RGB.

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).Plot3();

Plot3D(options)

Plot segmentation surface of tube.

Parameters

color – OPTIONAL default = ‘k’ color of surface. Can be any MATLAB accepted color format, e.g. RGB.
alpha (float) – OPTIONAL default = 0.3 opacity of surface plot.
context (bool) – OPTIONAL default = true also plot adjacent tubes.
contextcolor – OPTIONAL default = ‘r’ color of adjacent tubes. Can be any MATLAB accepted color format, e.g. RGB.

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).Plot3D();

PlotSpline(options)

Plot the tube spline.

Parameters

color – OPTIONAL default = ‘k’ color of line. Can be any MATLAB accepted color format, e.g. RGB.
context (bool) – OPTIONAL default = true also plot adjacent tubes.
contextcolor – OPTIONAL default = ‘r’ color of adjacent tubes. Can be any MATLAB accepted color format, e.g. RGB.

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).PlotSpline();

PlotSplineVecs(options)

Plot the tangental vectors of the spline at arcpoints interval.

Parameters

subsamp – OPTIONAL default = ‘2’ divisive factor to
tangent (subsample the arcpoints. e.g. 2 = every 2nd arcpoint) –
vector. –

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).PlotSplineVecs();

PruneMeasure(var)

Prune any tube object property to the class set prunelength.

Uses the patchprop.arcpoints property to trim off the desired variable property at either end.

Parameters

var (matrix) – n x m dimensional array where n is the number of rings and m are the number of tube patches.

Returns

1 variable * prunedprop(matrix): n x -1 dimensional array after

pruning.

S2I(I1, I2, I3): Fast specific implementation of MATLAB’s sub2ind.

SetChildren(tube)

Set children of tube.

This method automatically invokes tube.Tube.SetParent() in the children tube specified.

Parameters: tube (tube.Tube) – list to set as children.

SetGeneration()

Identify and set the generation of this tube.

Counts the number of tube anscestors i.e. parents of parents up to parent of generation 0.

Warning

This will fail if there are more than two parent tubes.

SetParent(tube)

Set parent of tube.

Todo

set children tube of parent without being stuck in loop.

Parameters: tube (tube.Tube) – list to set as parent.

SetRegion(regiontype, value)

Set region classifcation of tube.

modifies tube.Tube.region such that tube.Tube.region.regiontype = value.

Parameters

regiontype (char) – name of the category to set this region. e.g. lobe
() (value) – value that this tube should be set for the given regiontype. e.g. LLL for Left lower Lobe.

SetRegionDescendants(regiontype, value)

Set region classifcation of tube for current and all children.

Parameters

regiontype – See tube.Tube.SetRegion()
value – See tube.Tube.SetRegion()

SetRegionGeneration(regiontype)

set generation by given region to region property

Example

>>> AQnet.tubes(1).SetRegionGeneration('lobe')
>>> AQnet.tubes(1).region.lobe_gen

Todo

needs attention

Parameters: regiontype – See tube.Tube.SetRegion()

Tube(network, skelpoints, ID)

Init Tube see tube.Tube.

Makes the Tube object by defining the skelpoints along the centreline of the tube. This init method automatically interpolates the tube and fits a spline. The network object is required as it specifies certain configuration properties. This function is not intended to be invoked directrly. Only by network.TubeNetwork.MakeTubes().

Todo

Generalise this init function so that empty tubes can be
created.
make it possible for tubes to be created independent of
network object.

Parameters

network – see tube.Tube.network
skelpoints – see tube.Tube.skelpoints
ID – see tube.Tube.ID

plot(options)

Line plot two object properties with linear regression line.

A versatile method for plotting two object properties or array with a linear regressed line ‘line of best fit’. With smoothing if desired.

Todo

add visualisation
link to plot

Parameters

X (tube.Tube property or array) – OPTIONAL default = :attr:`patchprop.arcpoints` Horizontal X axis property name.
Y (tube.Tube property or array) – OPTIONAL default = :attr:`diameters` Vertical Y axis property name.
smoothing (float) – OPTIONAL default = 1e-64 degree of smoothing of the line plot.
linespec (char) – OPTIONAL default = - linespec to specify style. see MATLAB’s plot function.

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).plot();

toGif(filename, options)

Save tube patches as an animated series gif image.

Todo

showcase example

Parameters

filename (char) – filename to save as.
type (char) – OPTIONAL `default = ‘source’ object property that is a 3D array to view.
rings (bool array) – OPTIONAL default = ones(1,size(:attr:`measures,1))` same length as number of measures per patch, i.e. number of rings. For each ring to visualise. All rings by default.
ellipses (bool) – OPTIONAL default = true to view ellipses of measure if available.
points (bool) – OPTIONAL default = true to view points of measure if available.
framerate (int) – OPTIONAL default = 20 framerate to save gif.

Returns

1 variable * s(orthosliceViewer): handle to created graphics

Example

>>> run CA_base.m;
>>> figure;
>>> AQnet.tubes(98).toGif();

tube.Airway

class tube.Airway(varargin)

Bases: tube.Tube

short desc

long desc

Parameters: x (type) –
Return type: y(type)

Airway(varargin)

short desc

long desc

Parameters: x (type) –
Return type: y(type)