Full API——scan（一）

以下内容均翻译自官方文档：https://pylidc.github.io/scan.html#pylidc.Scan，如有错误，欢迎指正，谢谢。

class pylidc.Scan(**kwargs)

Scan类引用来自LIDC的top-level XML文件。一个scan对象有很多pylidc.Annotation对象，这些Annotation对象对应scan的unblindedReadNodule XML属性。

• study_instance_uid：string – DICOM 属性 (0020,000D).
• series_instance_uid：string – DICOM 属性 (0020,000E).
• patient_id：string – 格式为“ LIDC-IDRI-dddd”的标识符，其中dddd是整数字符串，如0005。
• slice_thickness：float – DICOM 属性 (0018,0050).请注意，这可能不等于slice_spacing属性（请参见下文）
• slice_zvals：ndarray – 将扫描片（slices of scan）的 "z-values"（即ImagePositionPatient DICOM属性的最后一个坐标）作为一个递增排序的NumPy数组。
• pixel_spacing：float – 这个计算属性是切片坐标差的中值，即scan.slice_zvals。这个属性通常（但并不总是！）与slice_thickness属性相同。此外，slice_spacing并不一定意味着所有切片都有间距。
• pixel_spacing：float – Dicom 属性 (0028,0030).。这通常是两个值。LIDC中所有切片分辨率相同，所以这里只使用一个值。
• contrast_used：bool – 如果切片的DICOM文件有任何Contrast标签，就返回True。
• is_from_initial：bool – 表示该PatientID是否被标记为初始399版本的一部分。

一个使用Scan类的例子：

import pylidc as pl

scans = pl.query(pl.Scan).filter(pl.Scan.slice_thickness <= 1)
print(scans.count())
# => 97

scan = scans.first()
print(scan.patient_id,
      scan.pixel_spacing,
      scan.slice_thickness,
      scan.slice_spacing)
# => LIDC-IDRI-0066, 0.63671875, 0.6, 0.5

print(len(scan.annotations))
# => 11

一、Scan类的cluster_annotations方法

cluster_annotations(metric='min', tol=None, factor=0.9, min_tol=0.1, return_distance_matrix=False, verbose=True)

评估CT切片中哪些是同一个肺结节的注释。此方法通过计算注释间距离来聚类Scan对象中的所有结节注释。

参数：

• metric (string or callable, default 'min')：对于有效度量。如果可以调用，所提供的函数应该取两个Annotation对象并返回一个float，即isinstance( metric(ann1, ann2), float )。
• tol (float, default=None)：以毫米为单位的距离。当边界轮廓点之间的最小距离小于tol时，将对注释进行分组。如果 tol = None (默认值)，则使用 tol = scan.pixel_spacing。
• factor (float, default=0.9)：如果tol导致任何注释组中的注释超过4个，则tol乘以factor，然后再次执行分组。
• min_tol (float, default=0.1)：如果tol减少到min_tol以下，那么该例程就会结束。
• return_distance_matrix (bool, default False) ：可以选择返回用于产生聚类的距离矩阵。
• verbose (bool, default=True)：如果为True，则当tol <min_tol出现时，将显示警告消息。

返回值：

clusters ：clusters[i]是一个在Scan中引用相同肺结节的pylidc.Annotation对象的列表（列表中的对象标识的是同一个结节）。len(clusters)表示Scan中结节的数量。

首先使用提供的度量参数计算Scan的所有注释之间的 "距离 "矩阵d[i,j]。当d[i,j]<=tol时，注释被认为是相邻的。通过找到与这个相邻矩阵相关联的图的连接组件来确定annotation groups。

一个例子：

import pylidc as pl

scan = pl.query(pl.Scan).first()
nodules = scan.cluster_annotations()

print("This can has %d nodules." % len(nodules))
# => This can has 4 nodules.

for i,nod in enumerate(nodules):
    print("Nodule %d has %d annotations." % (i+1,len(nod)))
# => Nodule 1 has 4 annotations.
# => Nodule 2 has 4 annotations.
# => Nodule 3 has 1 annotations.
# => Nodule 4 has 4 annotations.

二、Scan类的get_path_to_dicom_files()方法​

获取相对于在pylidc配置文件中设置的根路径（即MAC和Linux中的~/.pylidc）下存储的DICOM文件路径。

1. 曾经，DICOM数据将被下载为：[...]/LIDC-IDRI/LIDC-IDRI-dddd/uid1/uid2/dicom_file.dcm（其中[...]是在pylidc配置文件中设置的基本路径；uid1是Scan.study_instance_uid；                                                                                                                                                           而uid2是Scan.series_instance_uid。）；
2. 然而，现在DICOM数据通常被下载为： [...]/LIDC-IDRI/LIDC-IDRI-dddd/???（其中"??? "是TCIA使用的未知文件夹层次惯例。）

对于方案1，首先检查根路径中是否存在 "LIDC-IDRI-dddd "文件夹。如果存在，那么我们递归搜索 "LIDC-IDRI-dddd "目录，直到找到正确的子文件夹，该子文件夹中包含一个具有正确的 study_instance_uid 和 series_instance_uid 的 DICOM 文件。

方案2的效率要低于方案1，但方案2是稳健的。

三、Scan类的load_all_dicom_images方法​

load_all_dicom_images(verbose=True)

 

加载与该scan对象相关的所有DICOM图像，并以列表形式返回。

参数：verbose (bool)：打开/关闭加载方式。

一个例子：

import pylidc as pl
import matplotlib.pyplot as plt

scan = pl.query(pl.Scan).first()

images = scan.load_all_dicom_images()
zs = [float(img.ImagePositionPatient[2]) for img in images]
print(zs[1] - zs[0], img.SliceThickness, scan.slice_thickness)

plt.imshow( images[0].pixel_array, cmap=plt.cm.gray )
plt.show()

四、Scan类的to_volume方法​

to_volume(verbose=True)

将扫描结果作为3D numpy数组返回。

五、Scan类的visualize方法​

visualize(annotation_groups=None)

将scan对象的切片可视化

参数：annotation_groups (注释对象列表，默认为None)：这个参数应该由cluster_annotations方法返回的对象提供。

一个例子：

import pylidc as pl

scan = pl.query(pl.Scan).first()
nodules = scan.cluster_annotations()

scan.visualize(annotation_groups=nodules)