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

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

Εγκατάσταση και εγκατάστασης

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

Δεν απαιτούνται πρόσθετα πακέτα συστήματος, εγχώριες επέκταση ή αλυσίδες εργαλείων συντάκτη. Η βιβλιοθήκη είναι καθαρή 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 ελέγχους δυαδικής κατά 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 (μεσαία, κάμερα ή φως) και ένα 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 δίνει τον κόσμο-διαστημό μετασχηματισμό ενός κόμβου μετά την συσσώρευση όλων των προγόνων μετατροπών:

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 Η οντότητα παρέχει πρόσβαση στα δεδομένα γεωμετρίας, συμπεριλαμβανομένων των σημείων ελέγχου (βερτικών), πολυγώνων και στοιχείων βερτεξίου για τα κανονικά, UVs και χρώματα.

Διαβάστε το Mesh Geometry

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)}")

Η πρόσβαση στα στοιχεία Vertex

Τα στοιχεία του Vertex φέρουν δεδομένα per-vertex ή per polygon. τα πιο κοινά στοιχεία είναι τα κανονικά, οι συντονισμοί UV, τα χρώματα του vertex και οι ομάδες σκούπας:

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 (Παραδομήστε το δέρμα) και PhongMaterial (συνήθως σκιά). και οι δύο φορτώνται αυτόματα από τα αρχεία .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 Η ενότητα παρέχει όλους τους γεωμετρικούς τύπους μαθηματικών που απαιτούνται για την κατασκευή σκηνής και την επιθεώρηση.

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

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}")

Ετικέτες: Bounding Box

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 παρέχει ένα μοντέλο κινουμένων σχεδίων με βάση το AnimationClip, AnimationNode, KeyFrame,και KeyframeSequence.Τα δεδομένα κινουμένων σχεδίων που αποθηκεύονται σε φορτωμένα αρχεία (glTF, COLLADA) είναι προσβάσιμα μέσω αυτών των αντικειμένων.

Διαβάστε Κλιπ Animation

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

Αποθηκεύστε ξανά ένα κατάλογο ξεχωριστών αρχείων κλωστογραφίας + ως αυτόνομες δυαδικές 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}"
    )

Συμβουλές και βέλτιστες πρακτικές

Τρόπος επιλογής

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

Συντονιστικά συστήματα

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

Ομαλοποίηση

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

ΠΕΡΙΟΔΟΣ

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

Λάθος χειρισμού

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

κοινά ζητήματα

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

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

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

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

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

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

Συνοπτική αναφορά API

Κύρια τάξεις

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

Γεωμετρία

• Mesh:Πολυγώνιο με control_points (επίσημη λίστα) και polygons.
• VertexElementNormal:• Per-vertex ή per-polygon κανονικοί vectors.
• VertexElementUV:• Ο συντονιστής UV-εξέγερσης.
• VertexElementVertexColor:Πληροφορίες χρωμάτων Pervertex.
• VertexElementSmoothingGroup:• Ομάδα Polygon.

Υλικά

• LambertMaterial:• Το μοντέλο διανομής με diffuse_color και emissive_color.
• PhongMaterial: Specular Shading μοντέλο προσθήκη specular_color και shininess.

Η χρήση των υλικών (aspose.threed.utilities)

• Vector2:2D εμβολιασμός.
• Vector3:3D διπλή ακρίβεια vector.
• Vector4:4D διπλή ακρίβεια vector.
• FVector3:3D μονάδα με ακρίβεια.
• Quaternion:• Καρταρίνη με from_angle_axis() και to_matrix().
• Matrix4:4×4 μετασχηματιστική ματρίκα.
• BoundingBox: Αξικό-αλληλογημένο πλαίσιο με minimum και maximum Γωνίες .

ΑΜΝΗΤΗΣΕΙΣ

• AnimationClip: Ονομαστικό δοχείο για ένα σύνολο καναλιών κινούμενων και τα κλειδιά τους.
• AnimationNode: Per-node δεδομένα κινουμένων σχεδίων μέσα σε ένα κλίπ.
• KeyFrame:• Μοναδικό κλειδί με χρόνο και αξία.
• KeyframeSequence: Η παραγγελία της σειράς των κλειδιών για ένα μόνο κινούμενο χαρακτηριστικό.

Εισαγωγή / Αποθήκευση Επιλογών

• ObjLoadOptions: Ορισμένες ρυθμίσεις φόρτωσης OBJ: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL-συσσωρεύσεις ρυθμίσεις (βινική κατά ASCII λειτουργία).

Καμερες και Φωτα

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