Χαρακτηριστικά και Λειτουργίες

Aspose.3D FOSS για Python παρέχει ένα πλήρες API γραφήματος σκηνής για ανάγνωση, κατασκευή και εγγραφή 3D περιεχομένου σε πολλαπλές βιομηχανικές μορφές. Αυτή η σελίδα τεκμηριώνει κάθε κύρια περιοχή λειτουργίας με λειτουργικά παραδείγματα κώδικα Python που χρησιμοποιούν το πραγματικό API της βιβλιοθήκης.

Εγκατάσταση και Ρύθμιση

Εγκαταστήστε τη βιβλιοθήκη από το PyPI με μία εντολή:

pip install aspose-3d-foss

Δεν απαιτούνται πρόσθετα πακέτα συστήματος, εγγενείς επεκτάσεις ή αλυσίδες εργαλείων μεταγλωττιστή. Η βιβλιοθήκη είναι καθαρή Python και υποστηρίζει Python 3.7 έως 3.12 σε Windows, macOS και Linux.

Για να επαληθεύσετε την εγκατάσταση:

from aspose.threed import Scene

scene = Scene()
print("Aspose.3D FOSS installed successfully")
print(f"Root node name: {scene.root_node.name}")

Χαρακτηριστικά και Λειτουργίες

Υποστήριξη Μορφών

Aspose.3D FOSS για Python διαβάζει και γράφει τις ακόλουθες μορφές:

Φόρτωση OBJ με Επιλογές

ObjLoadOptions ελέγχει πώς γίνεται η ανάλυση των αρχείων OBJ:

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

options = ObjLoadOptions()
options.enable_materials = True        # Load accompanying .mtl file
options.flip_coordinate_system = False # Preserve original handedness
options.normalize_normal = True        # Normalize vertex normals to unit length
options.scale = 1.0                    # Apply a uniform scale factor at load time

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

print(f"Loaded {len(scene.root_node.child_nodes)} top-level nodes")

Αποθήκευση σε STL

StlSaveOptions ελέγχει την έξοδο δυαδική vs. ASCII και άλλες ρυθμίσεις ειδικές για STL:

from aspose.threed import Scene
from aspose.threed.formats import StlSaveOptions

scene = Scene.from_file("model.obj")
options = StlSaveOptions()
scene.save("output.stl", options)

Γράφημα Σκηνής

Όλο το 3D περιεχόμενο οργανώνεται ως δέντρο από Node αντικείμενα. Η ρίζα του δέντρου είναι scene.root_node. Κάθε κόμβος μπορεί να περιέχει υποκόμβους και να μεταφέρει ένα Entity (mesh, camera, or light) συν ένα Transform.

Διαπέραση της Ιεραρχίας Σκηνής

from aspose.threed import Scene

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

def traverse(node, depth=0):
    indent = "  " * depth
    entity_type = type(node.entity).__name__ if node.entity else "none"
    print(f"{indent}{node.name} [{entity_type}]")
    for child in node.child_nodes:
        traverse(child, depth + 1)

traverse(scene.root_node)

Δημιουργία Σκηνής Προγραμματιστικά

from aspose.threed import Scene, Node, Entity
from aspose.threed.entities import Mesh
from aspose.threed.utilities import Vector3

scene = Scene()
root = scene.root_node

##Create a child node and position it
child = root.create_child_node("my_object")
child.transform.translation = Vector3(1.0, 0.0, 0.0)
child.transform.scaling = Vector3(2.0, 2.0, 2.0)

scene.save("constructed.glb")

Επιθεώρηση GlobalTransform

GlobalTransform δίνει το world-space transform ενός κόμβου μετά τη συσσώρευση όλων των μετασχηματισμών των προγόνων:

from aspose.threed import Scene

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

for node in scene.root_node.child_nodes:
    gt = node.global_transform
    print(f"Node: {node.name}")
    print(f"  World translation: {gt.translation}")
    print(f"  World scale: {gt.scale}")

Mesh API

Το Mesh Η οντότητα παρέχει πρόσβαση σε δεδομένα γεωμετρίας, συμπεριλαμβανομένων των σημείων ελέγχου (κορυφές), πολυγώνων και στοιχείων κορυφής για κανονικές, UVs και χρώματα.

Ανάγνωση Γεωμετρίας Mesh

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

options = ObjLoadOptions()
options.enable_materials = True
options.flip_coordinate_system = False

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

for node in scene.root_node.child_nodes:
    if node.entity is None:
        continue
    mesh = node.entity
    print(f"Mesh: {node.name}")
    print(f"  Vertices: {len(mesh.control_points)}")
    print(f"  Polygons: {len(mesh.polygons)}")

Πρόσβαση σε Στοιχεία Κορυφής

Τα στοιχεία κορυφής μεταφέρουν δεδομένα ανά κορυφή ή ανά πολύγωνο. Τα πιο συνηθισμένα στοιχεία είναι οι κανονικές, οι συντεταγμένες UV, τα χρώματα κορυφής και οι ομάδες εξομάλυνσης:

from aspose.threed import Scene
from aspose.threed.entities import VertexElementNormal, VertexElementUV

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

for node in scene.root_node.child_nodes:
    if node.entity is None:
        continue
    mesh = node.entity

    # Iterate vertex elements to find normals and UVs
    for element in mesh.vertex_elements:
        if isinstance(element, VertexElementNormal):
            print(f"  Normals count: {len(element.data)}")
        elif isinstance(element, VertexElementUV):
            print(f"  UV count: {len(element.data)}")

Σύστημα Υλικών

Aspose.3D FOSS υποστηρίζει δύο τύπους υλικού: LambertMaterial (diffuse shading) και PhongMaterial (specular shading). Και τα δύο φορτώνονται αυτόματα από αρχεία .mtl όταν χρησιμοποιείται ObjLoadOptions με enable_materials = True.

Ανάγνωση Υλικών από OBJ

from aspose.threed import Scene
from aspose.threed.shading import LambertMaterial, PhongMaterial
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.enable_materials = True

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

for node in scene.root_node.child_nodes:
    mat = node.material
    if mat is None:
        continue
    print(f"Node: {node.name}")
    if isinstance(mat, PhongMaterial):
        print(f"  Type: Phong")
        print(f"  Diffuse: {mat.diffuse_color}")
        print(f"  Specular: {mat.specular_color}")
    elif isinstance(mat, LambertMaterial):
        print(f"  Type: Lambert")
        print(f"  Diffuse: {mat.diffuse_color}")

Ανάθεση Υλικού Προγραμματιστικά

from aspose.threed import Scene, Node
from aspose.threed.shading import PhongMaterial
from aspose.threed.utilities import Vector3

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

material = PhongMaterial()
material.diffuse_color = Vector3(0.8, 0.2, 0.2)   # Red diffuse
material.specular_color = Vector3(1.0, 1.0, 1.0)  # White specular

##Apply to the first mesh node
for node in scene.root_node.child_nodes:
    if node.entity is not None:
        node.material = material
        break

scene.save("recolored.glb")

Βοηθητικά Μαθηματικά

Το aspose.threed.utilities Το module παρέχει όλους τους γεωμετρικούς τύπους μαθηματικών που χρειάζονται για την κατασκευή και την επιθεώρηση της σκηνής.

Εργασία με Μετασχηματισμούς

from aspose.threed.utilities import Vector3, Quaternion, Matrix4
import math

##Build a rotation quaternion from axis-angle
axis = Vector3(0.0, 1.0, 0.0)          # Y-axis
angle_rad = math.radians(45.0)
q = Quaternion.from_angle_axis(angle_rad, axis)

print(f"Quaternion: x={q.x:.4f} y={q.y:.4f} z={q.z:.4f} w={q.w:.4f}")

##Convert to rotation matrix
mat = q.to_matrix()
print(f"Rotation matrix row 0: {mat[0, 0]:.4f} {mat[0, 1]:.4f} {mat[0, 2]:.4f}")

Υπολογισμός Περιβάλλουσας

from aspose.threed import Scene

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

# NOTE: mesh.get_bounding_box() is a stub — it always returns an empty BoundingBox()
# regardless of geometry. Compute bounds manually from control_points:
for node in scene.root_node.child_nodes:
    if node.entity is None:
        continue
    mesh = node.entity
    pts = mesh.control_points  # returns a copy of the vertex list
    if not pts:
        continue
    xs = [p.x for p in pts]
    ys = [p.y for p in pts]
    zs = [p.z for p in pts]
    print(f"Mesh: {node.name}")
    print(f"  Min: ({min(xs):.3f}, {min(ys):.3f}, {min(zs):.3f})")
    print(f"  Max: ({max(xs):.3f}, {max(ys):.3f}, {max(zs):.3f})")

Κίνηση

Aspose.3D FOSS παρέχει ένα μοντέλο animation βασισμένο σε AnimationClip, AnimationNode, KeyFrame, και KeyframeSequence. Τα δεδομένα animation που αποθηκεύονται σε φορτωμένα αρχεία (glTF, COLLADA) είναι προσβάσιμα μέσω αυτών των αντικειμένων.

Ανάγνωση Κλιπς Κίνησης

from aspose.threed import Scene

scene = Scene.from_file("animated.glb")

for clip in scene.animation_clips:
    print(f"Clip: {clip.name}  ({clip.start:.2f}s – {clip.stop:.2f}s)")
    for anim_node in clip.animations:
        print(f"  Animation node: {anim_node.name}")
        for sub in anim_node.sub_animations:
            print(f"    Sub-animation: {sub.name}")
        for bp in anim_node.bind_points:
            print(f"    Bind point: {bp.name}")

Επιλογές Φόρτωσης και Αποθήκευσης

Κάθε υποστηριζόμενη μορφή διαθέτει μια αντίστοιχη κλάση επιλογών που ελέγχει τη συμπεριφορά ανάλυσης και σειριοποίησης.

Παραδείγματα Χρήσης

Παράδειγμα 1: Μετατροπή Μορφής OBJ σε STL

Μετατρέψτε ένα αρχείο OBJ (με υλικά) σε δυαδικό STL, εκτυπώνοντας στατιστικά του πλέγματος κατά τη διαδικασία:

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

##Load OBJ with material support
load_opts = ObjLoadOptions()
load_opts.enable_materials = True
load_opts.flip_coordinate_system = False
load_opts.normalize_normal = True

scene = Scene()
scene.open("input.obj", load_opts)

##Report what was loaded
total_vertices = 0
total_polygons = 0
for node in scene.root_node.child_nodes:
    if node.entity is not None:
        mesh = node.entity
        total_vertices += len(mesh.control_points)
        total_polygons += len(mesh.polygons)
        print(f"  {node.name}: {len(mesh.control_points)} vertices, {len(mesh.polygons)} polygons")

print(f"Total: {total_vertices} vertices, {total_polygons} polygons")

##Save as STL
save_opts = StlSaveOptions()
scene.save("output.stl", save_opts)
print("Saved output.stl")

Παράδειγμα 2: Συγκέντρωση Πολλαπλών glTF σε GLB

Αποθηκεύστε ξανά έναν φάκελο με ξεχωριστά αρχεία glTF + υφής ως αυτόνομα δυαδικά αρχεία GLB:

import os
from aspose.threed import Scene

input_dir = "gltf_files"
output_dir = "glb_files"
os.makedirs(output_dir, exist_ok=True)

for filename in os.listdir(input_dir):
    if not filename.endswith(".gltf"):
        continue
    src = os.path.join(input_dir, filename)
    dst = os.path.join(output_dir, filename.replace(".gltf", ".glb"))
    scene = Scene.from_file(src)
    scene.save(dst)
    print(f"Packed {filename} -> {os.path.basename(dst)}")

Παράδειγμα 3: Επιθεώρηση Γραφήματος Σκηνής και Αναφορά Εξαγωγής

Περιηγηθείτε στο γράφημα σκηνής ενός αρχείου COLLADA, συλλέξτε στατιστικά ανά πλέγμα και εκτυπώστε μια δομημένη αναφορά:

from aspose.threed import Scene

scene = Scene.from_file("assembly.dae")

report = []

def collect(node, path=""):
    full_path = f"{path}/{node.name}" if node.name else path
    if node.entity is not None:
        mesh = node.entity
        gt = node.global_transform
        report.append({
            "path": full_path,
            "vertices": len(mesh.control_points),
            "polygons": len(mesh.polygons),
            "world_x": gt.translation.x,
            "world_y": gt.translation.y,
            "world_z": gt.translation.z,
        })
    for child in node.child_nodes:
        collect(child, full_path)

collect(scene.root_node)

print(f"{'Path':<40} {'Verts':>6} {'Polys':>6} {'X':>8} {'Y':>8} {'Z':>8}")
print("-" * 78)
for entry in report:
    print(
        f"{entry['path']:<40} "
        f"{entry['vertices']:>6} "
        f"{entry['polygons']:>6} "
        f"{entry['world_x']:>8.3f} "
        f"{entry['world_y']:>8.3f} "
        f"{entry['world_z']:>8.3f}"
    )

Συμβουλές και Καλές Πρακτικές

Επιλογή Μορφής

• glTF 2.0 / GLB είναι η προτεινόμενη μορφή ανταλλαγής για σκηνές που περιλαμβάνουν υλικά, κινούμενα σχέδια και σύνθετες ιεραρχίες. Προτιμήστε το GLB (δυαδικό) αντί για το glTF (κείμενο + εξωτερικά αρχεία) για φορητότητα.
• STL είναι η σωστή επιλογή όταν ο καταναλωτής downstream είναι ένας slicer, εργαλείο CAD ή οποιοδήποτε εργαλείο που χρειάζεται μόνο γεωμετρία. Το STL δεν περιέχει δεδομένα υλικού ή κίνησης.
• OBJ υποστηρίζεται ευρέως και είναι καλή επιλογή όταν πρέπει να ανταλλαχθούν δεδομένα υλικού με παλαιότερα εργαλεία. Πάντα διατηρείτε το αρχείο .mtl δίπλα στο αρχείο .obj.

Συστήματα Συντεταγμένων

• Διαφορετικές εφαρμογές χρησιμοποιούν διαφορετικές συμβάσεις χεριότητας. Ορίστε ObjLoadOptions.flip_coordinate_system = True κατά την εισαγωγή αρχείων OBJ από εργαλεία που χρησιμοποιούν δεξιόχειρο σύστημα συντεταγμένων εάν η αλυσίδα επεξεργασίας σας αναμένει αριστερόχειρες συντεταγμένες, και αντίστροφα.
• Επαληθεύστε τη σύμβαση αξόνων του πηγαίου περιουσιακού στοιχείου πριν εφαρμόσετε οποιαδήποτε αντιστροφή. Η διπλή αντιστροφή παράγει λανθασμένη γεωμετρία.

Κανονικοποίηση

• Πάντα ορίστε ObjLoadOptions.normalize_normal = True όταν η αλυσίδα επεξεργασίας downstream αναμένει μοναδιαίους κανονικούς (π.χ., όταν περνάτε κανονικούς σε shader ή κάνετε υπολογισμούς φωτισμού με εσωτερικό γινόμενο). Οι μη κανονικοποιημένοι κανονικοί από κακώς διαμορφωμένα αρχεία OBJ προκαλούν ελαφριά σφάλματα φωτισμού.

Απόδοση

• Φορτώστε τα αρχεία μία φορά και μετασχηματίστε το γράφημα σκηνής στη μνήμη αντί να τα ξαναφορτώνετε από το δίσκο για κάθε μορφή εξόδου. Ένα μόνο Scene.from_file() κάλεσμα ακολουθούμενο από πολλαπλά scene.save() κλήσεις είναι πιο αποδοτικό από επαναλαμβανόμενα φορτώματα.
• Κατά την επεξεργασία μεγάλων παρτίδων, δημιουργήστε ένα μόνο ObjLoadOptions ή StlSaveOptions αντικείμενο και επαναχρησιμοποιήστε το σε όλα τα αρχεία αντί να δημιουργείτε νέο αντικείμενο επιλογών ανά αρχείο.

Διαχείριση Σφαλμάτων

• Τυλίξτε scene.open() και scene.save() κλήσεις σε try/except blocks όταν επεξεργάζεστε μη αξιόπιστα ή παρεχόμενα από τον χρήστη αρχεία. Αναφέρετε το όνομα αρχείου στα μηνύματα εξαίρεσης για να απλοποιήσετε την αποσφαλμάτωση σε batch pipelines.

Κοινά Προβλήματα

Συχνές Ερωτήσεις

Ποιες εκδόσεις του Python υποστηρίζονται;? Python 3.7, 3.8, 3.9, 3.10, 3.11 και 3.12 υποστηρίζονται όλα. Η βιβλιοθήκη είναι καθαρή Python χωρίς καμία εγγενή επέκταση, έτσι λειτουργεί σε οποιαδήποτε πλατφόρμα όπου τρέχει το CPython.

Η βιβλιοθήκη έχει εξωτερικές εξαρτήσεις;? Όχι. Το Aspose.3D FOSS για Python χρησιμοποιεί μόνο τη στάνταρ βιβλιοθήκη του Python. Εγκαθίσταται ως ένα μόνο pip install aspose-3d-foss εντολή χωρίς περαιτέρω βήματα.

Υποστηρίζεται το FBX;? Ο FBX tokenizer έχει υλοποιηθεί και μπορεί να αναλύσει το δυαδικό ρεύμα διακριτικών FBX, αλλά ο δημιουργός γραφήματος σκηνής πάνω από τον tokenizer έχει γνωστά σφάλματα και δεν είναι έτοιμος για παραγωγή. Χρησιμοποιήστε OBJ, STL, glTF, COLLADA ή 3MF για αξιόπιστη χρήση σε παραγωγή.

Μπορώ να χρησιμοποιήσω το Aspose.3D FOSS σε εμπορικό προϊόν;? Ναι. Η βιβλιοθήκη διατίθεται υπό την άδεια MIT, η οποία επιτρέπει τη χρήση σε ιδιόκτητο και εμπορικό λογισμικό χωρίς πληρωμές δικαιωμάτων, εφόσον συμπεριληφθεί η ειδοποίηση της άδειας.

Πώς μπορώ να αναφέρω ένα σφάλμα ή να ζητήσω ένα φορμάτ;? Ανοίξτε ένα ζήτημα στο αποθετήριο. Συμπεριλάβετε ένα ελάχιστο αρχείο αναπαραγωγής και την έκδοση Python, το λειτουργικό σύστημα και την έκδοση της βιβλιοθήκης από pip show aspose-3d-foss.

Περίληψη Αναφοράς API

Κύριες Κλάσεις

• Scene: Κοντέινερ ανώτερου επιπέδου για μια 3D σκηνή. Σημείο εισόδου για open(), from_file(), και save().
• Node: Κόμβος δέντρου στο γράφημα σκηνής. Φέρει entity, transform, global_transform, material, child_nodes, και name.
• Entity: Βασική κλάση για αντικείμενα που συνδέονται με κόμβους (Mesh, Camera, Light).
• Transform: Θέση, περιστροφή (Quaternion) και κλίμακα σε τοπικό χώρο για έναν κόμβο.
• GlobalTransform: Μετασχηματισμός σε παγκόσμιο χώρο μόνο για ανάγνωση, υπολογιζόμενος με τη συσσώρευση όλων των μετασχηματισμών των προγόνων.

Geometry

• Mesh: Πολυγωνικό πλέγμα με control_points (λίστα κορυφών) και polygons.
• VertexElementNormal: Διανύσματα κανονικών ανά κορυφή ή ανά πολύγωνο.
• VertexElementUV: Συντεταγμένες υφής UV ανά κορυφή.
• VertexElementVertexColor: Δεδομένα χρώματος ανά κορυφή.
• VertexElementSmoothingGroup: Αναθέσεις ομάδων εξομάλυνσης πολύγωνων.

Υλικά

• LambertMaterial: Μοντέλο σκίασης διάχυσης με diffuse_color : και emissive_color.
• PhongMaterial: Μοντέλο σκίασης κατοπτρικής προσθέτοντας specular_color : και shininess.

: Βοηθητικά Μαθηματικά (aspose.threed.utilities)

• Vector2: Δι-διάστατο διάνυσμα.
• Vector3: Διάνυσμα 3Δ διπλής ακρίβειας.
• Vector4: Διάνυσμα 4Δ διπλής ακρίβειας.
• FVector3: Διάνυσμα 3Δ μονής ακρίβειας.
• Quaternion: Τετραδικό περιστροφής με from_angle_axis() και to_matrix().
• Matrix4: Πίνακας μετασχηματισμού 4×4.
• BoundingBox: Πλαίσιο περιέλιξης ευθυγραμμισμένο με άξονες με minimum και maximum γωνίες.

Κίνηση

• AnimationClip: Ονομαστικό κοντέινερ για ένα σύνολο καναλιών animation και τα keyframes τους.
• AnimationNode: Δεδομένα animation ανά κόμβο μέσα σε ένα clip.
• KeyFrame: Μονό keyframe με χρόνο και τιμή.
• KeyframeSequence: Ταξινομημένη ακολουθία keyframes για μια μοναδική animated ιδιότητα.

Επιλογές Φόρτωσης / Αποθήκευσης

• ObjLoadOptions: Ρυθμίσεις φόρτωσης ειδικές για OBJ: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: Ρυθμίσεις αποθήκευσης ειδικές για STL (binary vs. ASCII).

Κάμερες και Φώτα

• Camera: Οντότητα κάμερας με ρυθμίσεις προβολής, συνδέσιμη σε ένα Node.
• Light: Οντότητα πηγής φωτός, προσαρτήσιμη σε ένα Node.