聚类数据点

DataPoint、Cluster 和 ClusterCollection 是一个小型、通用的层次聚合聚类工具包，随 Aspose.PDF FOSS 一起捆绑用于 Python。它们是通用的数据分组原语——坐标加标签的点、一组项目以及一组集合——而不是针对 PDF 的文档特性；本模块不读取也不写入 PDF 内容。当你的代码需要将数值（例如你已经从文档中提取的测量值）分组为簇并用其质心对簇进行概括时，可使用它们。

表示数据点

DataPoint 将标识性的 name 与一个 value 数字坐标列表配对。构造后，两者分别以 DataPoint.name 和 DataPoint.value 形式公开。

构建和复制簇

Cluster 将可选的项目列表包装成一个单一的组。Cluster.count 报告簇当前持有的项目数量，Cluster.contains() 检查给定项目是否为成员，Cluster.clone() 返回一个由其自身项目列表支持的独立副本。Cluster.empty() 返回一个共享的、单例的空簇实例，而不是在每次调用时分配新的实例。

在集合中对簇进行分组

ClusterCollection 将可选的 Cluster 实例列表包装成单个集合，提供一个对象，以便在函数一次需要接受或返回多个集群时传递。

计算集群质心

DataPoint.get_centroid() 对 Cluster 中每个数据点的坐标逐位求平均，并返回一个表示质心的新 DataPoint。集群中的每个点在 DataPoint.value 中必须具有相同的维度数，平均才有意义。

提示与最佳实践

在一个集群内保持每个 DataPoint.value 列表长度相同 —— DataPoint.get_centroid() 逐位对坐标求平均，因此维度不匹配会产生误导性的质心。
在仅需要占位值时，使用 Cluster.empty() 作为共享的单例空集群，而不是每次都构造一个新的空集群。
在修改仍需在其他地方保留原始副本的集群之前，调用 Cluster.clone() —— 克隆会复制项列表而不是创建别名。
当函数需要以单个值接受或返回多个 Cluster 时，使用 ClusterCollection。
这些类是通用工具，而不是 PDF 解析功能——请将它们与您自己的逻辑结合使用，以从文档数据中生成 DataPoint 值。

常见问题

问题	原因	解决方案
`DataPoint.get_centroid()` 生成了具有意外数量值的质心	聚类中的数据点拥有不同长度的 `DataPoint.value` 列表	确保每个添加到 `Cluster` 的 `DataPoint` 具有相同的维度
`Cluster.contains()` 为您期望存在的值返回了 `False`	成员资格是直接针对存储的项目对象进行检查的，因此两个分别构造的具有相同名称和值的 `DataPoint` 实例不会在基于身份的查找中自动被视为相等	在假设成员关系之前，复用相同的 `DataPoint` 实例，或通过 `DataPoint.name` 和 `DataPoint.value` 进行比较
对克隆的集群进行变异也会修改原始集群	`Cluster.clone()` 被跳过，且共享了相同的 `Cluster` 引用，而不是复制	每当调用者需要独立副本时，请首先调用 `Cluster.clone()`

FAQ

`Cluster` 与 `ClusterCollection` 有什么区别？

Cluster 包含一个项目列表——通常是 DataPoint 实例——属于同一组。ClusterCollection 包含一系列 Cluster 对象：它将簇进行分组，而不是单个数据点。

`DataPoint.get_centroid()` 会修改其提供的簇吗？

不会。它读取已提供的 Cluster 中的项目，并返回一个新的 DataPoint 作为质心；源簇及其项目保持不变。

此聚类功能是否仅针对 PDF 内容？

注：DataPoint、Cluster和ClusterCollection是随 aspose_pdf 包一起提供的通用数值聚类原语。它们本身不会读取页面、文本或任何其他 PDF 结构——仅对您构造时提供的数值进行操作。

为什么 `Cluster.empty()` 每次都返回相同的实例？

Cluster.empty() 返回一个共享的单例，以便对“no cluster”的重复调用不会在每次调用时分配新对象。

API Reference 摘要

类/方法	描述
`DataPoint`	一个命名点，持有数值坐标列表
`DataPoint.name`	点的标识名称
`DataPoint.value`	点的数值坐标列表
`DataPoint.get_centroid()`	返回一个新的 `DataPoint`，其对聚类中每个点的坐标取平均
`Cluster`	一组项目，通常是 `DataPoint` 实例
`Cluster.empty()`	返回共享的空簇单例
`Cluster.contains()`	检查项是否在簇中
`Cluster.clone()`	返回该簇的独立副本
`Cluster.count`	簇中当前的项目数量
`ClusterCollection`	将一系列 `Cluster` 实例包装成一个集合

另请参阅

Aspose.PDF for Python — Enterprise Documentation

聚类数据点