كيفية تحميل نماذج ثلاثية الأبعاد في بايثون

Aspose.3D FOSS for Python يوفر واجهة برمجة تطبيقات بسيطة لفتح ملفات 3D دون أي تبعيات أصلية. بعد تحميل ملف إلى كائن Scene، يمكنك استعراض تسلسل العقد وقراءة بيانات الهندسة الخام لكل شبكة في المشهد.

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

pip install aspose-3d-foss

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

##Automatic format detection
scene = Scene.from_file("model.obj")

scene = Scene()
scene.open("model.obj")

from aspose.threed import Scene, Node

scene = Scene.from_file("model.obj")

def walk(node: Node, depth: int = 0) -> None:
    indent = "  " * depth
    print(f"{indent}Node: {node.name!r}")
    for child in node.child_nodes:
        walk(child, depth + 1)

walk(scene.root_node)

from aspose.threed import Scene
from aspose.threed.entities import Mesh

scene = Scene.from_file("model.obj")

for node in scene.root_node.child_nodes:
    for entity in node.entities:
        if isinstance(entity, Mesh):
            mesh: Mesh = entity
            print(f"Mesh '{node.name}': "
                  f"{len(mesh.control_points)} vertices, "
                  f"{len(mesh.polygons)} polygons")

            # First vertex position
            if mesh.control_points:
                v = mesh.control_points[0]
                print(f"  First vertex: ({v.x:.4f}, {v.y:.4f}, {v.z:.4f})")

            # First polygon face (list of control-point indices)
            if mesh.polygons:
                print(f"  First polygon: {mesh.polygons[0]}")

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.flip_coordinate_system = True   # Convert right-hand Y-up to Z-up
options.scale = 0.01                    # Convert centimetres to metres
options.enable_materials = True         # Load .mtl material file
options.normalize_normal = True         # Normalize all normals to unit length

scene = Scene()
scene.open("model.obj", options)

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

خطأ FileNotFoundError عند الاستدعاء Scene.from_file()

يجب أن يكون المسار مطلقًا أو نسبيًا صحيحًا بالنسبة إلى دليل العمل أثناء وقت التشغيل. استخدم pathlib.Path لإنشاء مسارات موثوقة:

from pathlib import Path
from aspose.threed import Scene

path = Path(__file__).parent / "assets" / "model.obj"
scene = Scene.from_file(str(path))

mesh.polygons فارغ بعد تحميل ملف STL

تخزن ملفات STL المثلثات كواجهات خام، وليس كشبكة مفهرسة. بعد التحميل، يتم تركيب المضلعات من تلك الواجهات. إذا ظهر polygons فارغًا، فافحص len(mesh.control_points)؛ إذا كان العدد مضاعفًا للعدد 3 فإن الهندسة مخزنة بصيغة غير مفهرسة وكل ثلاثية متتالية من الرؤوس تشكل مثلثًا واحدًا.

عدم توافق نظام الإحداثيات (النموذج يبدو مدورًا أو معكوسًا)

تستخدم الأدوات المختلفة اتفاقيات مختلفة (Y‑up مقابل Z‑up، اليد اليسرى مقابل اليد اليمنى). اضبط ObjLoadOptions.flip_coordinate_system = True أو طبّق دورانًا على Transform الخاص بالعقدة الجذرية بعد التحميل.

AttributeError: 'NoneType' object has no attribute 'polygons'

قد تحتوي قائمة الكيانات الخاصة بالعقدة على كيانات غير شبكية (كاميرات، أضواء). احرص دائمًا على الحماية باستخدام isinstance(entity, Mesh) قبل التحويل.

الأسئلة المتكررة (FAQ)

ما هي صيغ 3D التي يمكنني تحميلها؟

OBJ (Wavefront)، STL (ثنائي و ASCII)، glTF 2.0 / GLB، COLLADA (DAE)، و 3MF. يتم دعم تجزئة ملفات FBX جزئياً لكن التحليل الكامل لم يكتمل بعد.

هل تحميل ملف OBJ يحمل أيضًا مادة .mtl؟

نعم، عندما ObjLoadOptions.enable_materials = True (الإعداد الافتراضي). تبحث المكتبة عن ملف .mtl في نفس الدليل الذي يوجد فيه ملف .obj. إذا كان .mtl مفقودًا، لا يزال يتم تحميل الهندسة ويتم إصدار تحذير.

هل يمكنني تحميل ملف من تدفق بايت بدلاً من المسار؟

نعم. scene.open() يقبل أي كائن شبيه بالملف يحتوي على طريقة .read() بالإضافة إلى سلسلة مسار الملف. مرّر تدفقًا ثنائيًا مفتوحًا (مثلاً، io.BytesIO) مباشرة. Scene.from_file() يقبل فقط سلسلة مسار الملف.

كيف أحصل على المتجهات العمودية للسطح؟

بعد التحميل، تحقق من mesh.get_element(VertexElementType.NORMAL). تُعيد هذه VertexElementNormal التي تحتوي قائمة data فيها متجهًا عموديًا واحدًا لكل مرجع، مُطابقة وفقًا لـ mapping_mode و reference_mode.

from aspose.threed.entities import Mesh, VertexElementType

normals = mesh.get_element(VertexElementType.NORMAL)
if normals:
    print(normals.data[0])  # First normal vector

هل المكتبة آمنة من حيث الخيوط عند تحميل ملفات متعددة في وقت واحد؟

كل كائن Scene مستقل. تحميل ملفات منفصلة إلى مثيلات Scene منفصلة من خيوط منفصلة آمن طالما أنك لا تشارك Scene واحد عبر الخيوط دون قفل خارجي.