تجميع نقاط البيانات
تجميع نقاط البيانات
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()قبل تعديل عنقود لا زلت بحاجة إلى نسخه الأصلية في مكان آخر — النسخ ينشئ نسخة من قائمة العناصر بدلاً من الإشارة إليها. - استخدم
ClusterCollectionعندما تحتاج دالة إلى قبول أو إرجاع أكثر منClusterكقيمة واحدة. - هذه الفئات هي أدوات عامة، ليست ميزة تحليل PDF — اربطها بمنطقك الخاص لإنتاج قيم
DataPointمن بيانات المستند.
مشكلات شائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
DataPoint.get_centroid() ينتج مركزًا بعدد غير متوقع من القيم | نقاط البيانات في العنقود لديها قوائم DataPoint.value بأطوال مختلفة | تأكد من أن كل DataPoint تُضاف إلى Cluster لها نفس الأبعاد |
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 في مجموعة واحدة |
