كيفية العمل مع التجميع في Python

Aspose.PDF FOSS لـ Python يتضمن أداة تجميع هرمي تجميعي صغيرة وعامة الغرض — مستقلة عن أي عملية PDF واحدة — لتجميع الكائنات المرتبطة بـ DataPoint في حالات Cluster وحساب مركز الكتلة. أنت تقرر ما يمثله كل نقطة بيانات وتزود إحداثياتها بنفسك؛ الأداة لا تملأها تلقائيًا. يتم تثبيت المكتبة بالأمر أدناه.

دليل خطوة بخطوة

الخطوة 1: تثبيت الحزمة

تثبيت حزمة Aspose.PDF FOSS:

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

تحقق من التثبيت عن طريق استيراد Cluster وطباعة رسالة تأكيد:

from aspose_pdf import Cluster
print("aspose-pdf-foss-for-python is ready.")

الخطوة 2: استيراد الفئات المطلوبة

استورد الفئات الثلاث التي تشكل أداة التجميع:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

الخطوة 3: إنشاء نقاط البيانات

يقوم DataPoint بزوج سلسلة name مع قائمة value من القيم العائمة — الإحداثيات أو متجه الخصائص الذي تقرره ذا معنى لمنطق التجميع الخاص بك:

from aspose_pdf import DataPoint

point_a = DataPoint("item-1", [12.0, 45.0])
point_b = DataPoint("item-2", [13.5, 44.0])
point_c = DataPoint("item-3", [98.0, 5.0])

print(point_a.name, point_a.value)

لا يربط DataPoint value بأي مفهوم PDF معين — إحداثيات الصفحة، مقاييس الخط، أو أي متجه ميزات رقمي آخر كلها تعمل على قدم المساواة.

الخطوة 4: تجميع نقاط البيانات في عنقود

مرّر قائمة العضوية الكاملة إلى مُنشئ Cluster. لا توجد طريقة لإضافة عناصر إلى Cluster بعد بنائه، لذا قرّر العضوية أولاً:

from aspose_pdf import Cluster

nearby = Cluster([point_a, point_b])
print(nearby.count)              # 2
print(nearby.contains(point_a))  # True

contains() يتطابق عن طريق المساواة — DataPoint يحدد المساواة على name وvalue معًا، لذا فإن كائن DataPoint مختلف يحمل نفس الاسم والقيمة يُبلغ عنه أيضًا كمدمج.

الخطوة 5: حساب مركز العنقود

DataPoint.get_centroid(cluster) هي طريقة ثابتة تقوم بحساب المتوسط لكل بُعد من كل DataPoint.value في العنقود وتعيد النتيجة كـ DataPoint جديد يُدعى "centroid":

from aspose_pdf import DataPoint

centroid = DataPoint.get_centroid(nearby)
print(centroid.name)   # "centroid"
print(centroid.value)  # per-dimension average across the cluster

يجب أن تكون كل قائمة DataPoint.value في العنقود ذات نفس الطول — get_centroid تحسب المتوسط موضعًا بموضع ولا تتحقق من توافق الأطوال. استدعاؤها على Cluster.empty()، أو أي عنقود يحتوي على count == 0، يثير ValueError.

الخطوة 6: استنساخ عنقود أو إعادة استخدام المثيل الفارغ المشترك

clone() تُعيد Cluster مستقلة تحتوي على نفس العناصر؛ Cluster.empty() تُعيد دائمًا نفس المثيل المخزن مؤقتًا للعنقود الفارغ بدلاً من إنشاء واحد جديد:

from aspose_pdf import Cluster

backup = nearby.clone()
print(backup is nearby)          # False -- independent copy
print(backup.contains(point_a))  # True -- same items

placeholder = Cluster.empty()
print(placeholder.count)         # 0

الخطوة 7: تجميع عدة عنقودات في ClusterCollection

ClusterCollection يجمع عدة كائنات Cluster خلف حاوية واحدة تدعم len():

from aspose_pdf import Cluster, ClusterCollection

outliers = Cluster([point_c])
collection = ClusterCollection([nearby, outliers])
print(len(collection))  # 2

ClusterCollection لا يوفّر طريقة لاسترجاع عنقوداته مرة أخرى — احتفظ بإشارة إلى القائمة التي تمرّرها إلى المُنشئ إذا كنت بحاجة إلى تكرار العنقودات لاحقًا.

المشكلات الشائعة والحلول

لا توجد طريقة لإضافة عنصر إلى الموجود Cluster

Cluster لا يقبل قائمة الأعضاء إلا عند وقت الإنشاء (Cluster(items)). قم ببناء القائمة الكاملة من كائنات DataPoint أولاً، ثم أنشئ الـCluster — لا توجد add() أو append() للاتصال بها لاحقًا.

DataPoint.get_centroid() raises ValueError

يحدث هذا عندما يكون التجمع المُمرَّر فارغًا (count == 0)، بما في ذلك Cluster.empty(). تحقق من cluster.count قبل استدعاء get_centroid، أو عالج الاستثناء إذا كان التجمع الفارغ إدخالًا صالحًا في سير عملك.

قيم المركز تبدو خاطئة

get_centroid يجمع كل موضع من DataPoint.value موضعًا بموضع ويقسم على عدد النقاط — لا يتحقق من أن كل قائمة value في التجمع لها نفس الطول. دمج كائنات DataPoint ذات أبعاد غير متطابقة ينتج متوسطًا غير صحيح بصمت بدلاً من رفع استثناء.

Expecting Cluster.empty() لإنشاء مجموعة فارغة جديدة في كل مرة

Cluster.empty() هو موصل مفرد — كل استدعاء يُعيد نفس النسخة المخزنة مؤقتًا. استخدم Cluster() (بدون أي معاملات) بدلاً من ذلك إذا كنت بحاجة إلى مجموعة فارغة مستقلة ومتميزة.

توقع أن المكتبة تُجَمِّع النقاط تلقائيًا

DataPoint، Cluster، وClusterCollection هي هياكل بيانات لتمثيل النقاط، المجموعات، وحساب المركز — الوحدة لا تتضمن دالة ربط أو مسافة تُحدد أي النقاط تنتمي معًا. يُحدِّد كودك الخاص عضوية المجموعة قبل إنشاء Cluster.

الأسئلة المتكررة

هل تقوم هذه الوحدة تلقائيًا بتجميع نقاط البيانات حسب المسافة؟

لا. Cluster وDataPoint وClusterCollection هي مكوّنات أساسية لتمثيل التجميعات المحددة مسبقًا وحساب المركز — لا توجد خطوة تجميع مدمجة أو تعيين يعتمد على المسافة.

ما الفرق بين `Cluster()` و`Cluster.empty()`؟

Cluster(items=None) ينشئ نسخة جديدة في كل مرة يتم استدعاؤه. Cluster.empty() هي classmethod تُعيد نفس النسخة المخزنة المشتركة للفارغ-عنقود في كل استدعاء.

هل يمكنني إضافة عناصر إلى `Cluster` بعد إنشائه؟

لا. Cluster لا يعرض سوى contains() وclone() وخاصية count بعد الإنشاء — العضوية ثابتة بمجرد تشغيل المُنشئ.

هل يعمل `get_centroid()` مع أي عدد من الأبعاد؟

نعم، طالما أن كل قائمة DataPoint.value في العنقود لها نفس الطول. get_centroid تحسب متوسط كل بعد بشكل مستقل وتعيد النتيجة كـ DataPoint جديد.

ما الذي تضيفه `ClusterCollection` فوق قائمة Python العادية من العناقيد؟

في الأساس حاوية ذات نوع مع دعم len(). لا تضيف سلوك تكرار أو بحث أو دمج يتجاوز ما لديك بالفعل في القائمة التي بنيتها منها.