import numpy
import SimpleITK as sitk
from radiomics import base, cShape, deprecated
[docs]class RadiomicsShape2D(base.RadiomicsFeaturesBase):
r"""
In this group of features we included descriptors of the two-dimensional size and shape of the ROI. These features
are independent from the gray level intensity distribution in the ROI and are therefore only calculated on the
non-derived image and mask.
Unless otherwise specified, features are derived from the approximated shape defined by the circumference mesh. To
build this mesh, vertices (points) are first defined as points halfway on an edge between a pixel included in the ROI
and one outside the ROI. By connecting these vertices a mesh of connected lines is obtained, with each line
defined by 2 adjacent vertices, which shares each a point with exactly one other line.
This mesh is generated using an adapted version marching cubes algorithm. In this algorithm, a 2x2 square is moved
through the mask space (2d). For each position, the corners of the square are then marked 'segmented' (1) or
'not segmented' (0). Treating the corners as specific bits in a binary number, a unique square-index is obtained
(0-15). This index is then used to determine which lines are present in the square, which are defined in a lookup
table.
These lines are defined in such a way, that the normal of the triangle defined by these points and the origin
is always oriented in the a consistent direction. This results in signed values for the surface area of each triangle,
so that when summed, the superfluous (postive) area included by triangles partly inside and outside the ROI is
perfectly cancelled out by the (negative) area of triangles entirely outside the ROI.
Let:
- :math:`N_p` represent the number of pixels included in the ROI
- :math:`N_f` represent the number of lines defining the circumference (perimeter) Mesh.
- :math:`A` the surface area of the mesh in mm\ :sup:`2`, calculated by :py:func:`getMeshSurfaceFeatureValue`
- :math:`P` the perimeter of the mesh in mm, calculated by :py:func:`getPerimeterFeatureValue`
.. note::
This class can **only** be calculated for truly 2D masks. To ensure correct processing, it is required that
``force2D`` is set to ``True`` and ``force2Ddimension`` to the dimension that is out-of plane (e.g. 0 (z-axis) for
an axial slice). Furthermore, this dimension is required to have size 1. If not set correctly, a ValueError is
raised.
References:
- Lorensen WE, Cline HE. Marching cubes: A high resolution 3D surface construction algorithm. ACM SIGGRAPH Comput
Graph `Internet <http://portal.acm.org/citation.cfm?doid=37402.37422>`_. 1987;21:163-9.
"""
def __init__(self, inputImage, inputMask, **kwargs):
super(RadiomicsShape2D, self).__init__(inputImage, inputMask, **kwargs)
def _initVoxelBasedCalculation(self):
raise NotImplementedError('Shape features are not available in pixel-based mode')
def _initSegmentBasedCalculation(self):
self.maskArray = (sitk.GetArrayFromImage(self.inputMask) == self.label) # boolean array
Nd = self.inputMask.GetDimension()
if Nd == 3:
if not self.settings.get('force2D', False):
raise ValueError('Shape2D is can only be calculated when input is 2D or 3D with `force2D=True`')
force2DDimension = self.settings.get('force2Ddimension', 0)
axes = [0, 1, 2]
axes.remove(force2DDimension)
self.pixelSpacing = numpy.array(self.inputImage.GetSpacing()[::-1])[(axes,)]
if self.maskArray.shape[force2DDimension] > 1:
raise ValueError('Size of the mask in dimension %i is more than 1, cannot compute 2D shape')
# Drop the 2D axis, ensuring the input is truly 2D
self.maskArray = numpy.squeeze(self.maskArray, axis=force2DDimension)
elif Nd == 2:
self.pixelSpacing = numpy.array(self.inputImage.GetSpacing()[::-1])
else:
raise ValueError('Shape2D is can only be calculated when input is 2D or 3D with `force2D=True`')
# Pad maskArray to prevent index-out-of-range errors
self.logger.debug('Padding the mask with 0s')
self.maskArray = numpy.pad(self.maskArray, pad_width=1, mode='constant', constant_values=0)
self.labelledPixelCoordinates = numpy.where(self.maskArray != 0)
self.logger.debug('Pre-calculate surface, perimeter, diameter and eigenvalues')
# Volume, Surface Area and eigenvalues are pre-calculated
# Compute Surface Area and volume
self.Perimeter, self.Surface, self.Diameter = cShape.calculate_coefficients2D(self.maskArray, self.pixelSpacing)
# Compute eigenvalues and -vectors
Np = len(self.labelledPixelCoordinates[0])
coordinates = numpy.array(self.labelledPixelCoordinates, dtype='int').transpose((1, 0)) # Transpose equals zip(*a)
physicalCoordinates = coordinates * self.pixelSpacing[None, :]
physicalCoordinates -= numpy.mean(physicalCoordinates, axis=0) # Centered at 0
physicalCoordinates /= numpy.sqrt(Np)
covariance = numpy.dot(physicalCoordinates.T.copy(), physicalCoordinates)
self.eigenValues = numpy.linalg.eigvals(covariance)
# Correct machine precision errors causing very small negative eigen values in case of some 2D segmentations
machine_errors = numpy.bitwise_and(self.eigenValues < 0, self.eigenValues > -1e-10)
if numpy.sum(machine_errors) > 0:
self.logger.warning('Encountered %d eigenvalues < 0 and > -1e-10, rounding to 0', numpy.sum(machine_errors))
self.eigenValues[machine_errors] = 0
self.eigenValues.sort() # Sort the eigenValues from small to large
self.logger.debug('Shape feature class initialized')
[docs] def getMeshSurfaceFeatureValue(self):
r"""
**1. Mesh Surface**
.. math::
A_i = \frac{1}{2}\text{Oa}_i \times \text{Ob}_i \text{ (1)}
A = \displaystyle\sum^{N_f}_{i=1}{A_i} \text{ (2)}
where:
:math:`\text{O}_i\text{a}_i` and :math:`\text{O}_i\text{b}_i` are edges of the :math:`i^{\text{th}}` triangle in the
mesh, formed by vertices :math:`\text{a}_i`, :math:`\text{b}_i` of the perimiter and the origin :math:`\text{O}`.
To calculate the surface area, first the signed surface area :math:`A_i` of each triangle in the mesh is calculated
(1). The total surface area is then obtained by taking the sum of all calculated sub-areas (2), where the sign will
ensure correct surface area, as the negative area of triangles outside the ROI will cancel out the surplus area
included by triangles partly inside and partly outside the ROI.
"""
return self.Surface
[docs] def getPixelSurfaceFeatureValue(self):
r"""
**2. Pixel Surface**
.. math::
A_{pixel} = \displaystyle\sum^{N_v}_{k=1}{A_k}
The surface area of the ROI :math:`A_{pixel}` is approximated by multiplying the number of pixels in the ROI by the
surface area of a single pixel :math:`A_k`. This is a less precise approximation of the surface area.
This feature does not make use of the mesh and is not used in calculation of other 2D shape features.
"""
y, x = self.pixelSpacing
Np = len(self.labelledPixelCoordinates[0])
return Np * (x * y)
[docs] def getPerimeterFeatureValue(self):
r"""
**3. Perimeter**
.. math::
P_i = \sqrt{(\text{a}_i-\text{b}_i)^2} \text{ (1)}
P = \displaystyle\sum^{N_f}_{i=1}{P_i} \text{ (2)}
where:
:math:`\text{a}_i` and :math:`\text{b}_i` are vertices of the :math:`i^{\text{th}}` line in the
perimeter mesh.
To calculate the perimeter, first the perimeter :math:`A_i` of each line in the mesh circumference is calculated
(1). The total perimeter is then obtained by taking the sum of all calculated sub-areas (2).
"""
return self.Perimeter
[docs] def getPerimeterSurfaceRatioFeatureValue(self):
r"""
**4. Perimeter to Surface ratio**
.. math::
\textit{perimeter to surface ratio} = \frac{P}{A}
Here, a lower value indicates a more compact (circle-like) shape. This feature is not dimensionless, and is
therefore (partly) dependent on the surface area of the ROI.
"""
return self.Perimeter / self.Surface
[docs] def getSphericityFeatureValue(self):
r"""
**5. Sphericity**
.. math::
\textit{sphericity} = \frac{2\pi R}{P} = \frac{2\sqrt{\pi A}}{P}
Where :math:`R` is the radius of a circle with the same surface as the ROI, and equal to
:math:`\sqrt{\frac{A}{\pi}}`.
Sphericity is the ratio of the perimeter of the tumor region to the perimeter of a circle with
the same surface area as the tumor region and therefore a measure of the roundness of the shape of the tumor region
relative to a circle. It is a dimensionless measure, independent of scale and orientation. The value range is
:math:`0 < sphericity \leq 1`, where a value of 1 indicates a perfect circle (a circle has the smallest possible
perimeter for a given surface area, compared to other shapes).
.. note::
This feature is correlated to Spherical Disproportion. Therefore, only this feature is enabled by default.
"""
return (2 * numpy.sqrt(numpy.pi * self.Surface)) / self.Perimeter
[docs] @deprecated
def getSphericalDisproportionFeatureValue(self):
r"""
**6. Spherical Disproportion**
.. math::
\textit{spherical disproportion} = \frac{P}{2\sqrt{\pi A}}
Spherical Disproportion is the ratio of the perimeter of the tumor region to the perimeter of a circle with
the same surface area as the tumor region, and by definition, the inverse of Sphericity. Therefore, the value range
is :math:`spherical\ disproportion \geq 1`, with a value of 1 indicating a perfect sphere.
.. note::
This feature is correlated to Sphericity.
Therefore, this feature is marked, so it is not enabled by default (i.e. this feature will not be enabled if no
individual features are specified (enabling 'all' features), but will be enabled when individual features are
specified, including this feature). To include this feature in the extraction, specify it by name in the enabled
features.
"""
return 1.0 / self.getSphericityFeatureValue()
[docs] def getMaximumDiameterFeatureValue(self):
r"""
**7. Maximum 2D diameter**
Maximum diameter is defined as the largest pairwise Euclidean distance between tumor surface mesh
vertices.
"""
return self.Diameter
[docs] def getMajorAxisLengthFeatureValue(self):
r"""
**8. Major Axis Length**
.. math::
\textit{major axis} = 4 \sqrt{\lambda_{major}}
This feature yield the largest axis length of the ROI-enclosing ellipsoid and is calculated using the largest
principal component :math:`\lambda_{major}`.
The principal component analysis is performed using the physical coordinates of the pixel centers defining the ROI.
It therefore takes spacing into account, but does not make use of the shape mesh.
"""
if self.eigenValues[1] < 0:
self.logger.warning('Major axis eigenvalue negative! (%g)', self.eigenValues[1])
return numpy.nan
return numpy.sqrt(self.eigenValues[1]) * 4
[docs] def getMinorAxisLengthFeatureValue(self):
r"""
**9. Minor Axis Length**
.. math::
\textit{minor axis} = 4 \sqrt{\lambda_{minor}}
This feature yield the second-largest axis length of the ROI-enclosing ellipsoid and is calculated using the largest
principal component :math:`\lambda_{minor}`.
The principal component analysis is performed using the physical coordinates of the pixel centers defining the ROI.
It therefore takes spacing into account, but does not make use of the shape mesh.
"""
if self.eigenValues[0] < 0:
self.logger.warning('Minor axis eigenvalue negative! (%g)', self.eigenValues[0])
return numpy.nan
return numpy.sqrt(self.eigenValues[0]) * 4
[docs] def getElongationFeatureValue(self):
r"""
**10. Elongation**
Elongation shows the relationship between the two largest principal components in the ROI shape.
For computational reasons, this feature is defined as the inverse of true elongation.
.. math::
\textit{elongation} = \sqrt{\frac{\lambda_{minor}}{\lambda_{major}}}
Here, :math:`\lambda_{\text{major}}` and :math:`\lambda_{\text{minor}}` are the lengths of the largest and second
largest principal component axes. The values range between 1 (where the cross section through the first and second
largest principal moments is circle-like (non-elongated)) and 0 (where the object is a maximally elongated: i.e. a 1
dimensional line).
The principal component analysis is performed using the physical coordinates of the pixel centers defining the ROI.
It therefore takes spacing into account, but does not make use of the shape mesh.
"""
if self.eigenValues[0] < 0 or self.eigenValues[1] < 0:
self.logger.warning('Elongation eigenvalue negative! (%g, %g)', self.eigenValues[0], self.eigenValues[1])
return numpy.nan
return numpy.sqrt(self.eigenValues[0] / self.eigenValues[1])