Özellikler ve İşlevsellikler

Aspose.3D FOSS for Python, çoklu endüstri standardı formatlarda 3D içeriği okuma, oluşturma ve yazma için eksiksiz bir sahne grafiği API’si sağlar. Bu sayfa, gerçek kütüphane API’sini kullanan çalışan Python kod örnekleriyle her ana özellik alanını belgelemektedir.

Kurulum ve Ayarlama

Kütüphaneyi tek bir komutla PyPI’dan kurun:

pip install aspose-3d-foss

Ek sistem paketleri, yerel uzantılar veya derleyici araç zincirleri gerekmez. Kütüphane saf Pythondır ve Python 3.7’den 3.12’ye kadar Windows, macOS ve Linux’ta desteklenir.

Kurulumu doğrulamak için:

from aspose.threed import Scene

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

Özellikler ve İşlevsellikler

Format Desteği

Aspose.3D FOSS for Python, aşağıdaki formatları okur ve yazar:

Seçeneklerle OBJ Yükleme

ObjLoadOptions OBJ dosyalarının nasıl ayrıştırılacağını kontrol eder:

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’ye Kaydetme

StlSaveOptions ikili ve ASCII çıktıyı ve diğer STL-özel ayarları kontrol eder:

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

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

Sahne Grafiği

Tüm 3D içerik bir ağaç şeklinde düzenlenir Node nesneler. Ağacın kökü scene.root_node. Her düğüm alt düğümler içerebilir ve bir Entity (mesh, camera, or light) ve bir Transform.

Sahne Hiyerarşisini Gezinme

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)

Programlı Olarak Bir Sahne Oluşturma

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’ı İnceleme

GlobalTransform bir düğümün tüm ata dönüşümlerini biriktirdikten sonra dünya-uzayı dönüşümünü verir:

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

Bu Mesh varlık, kontrol noktaları (köşe noktaları), çokgenler ve normaller, UV’ler ve renkler için köşe öğeleri dahil olmak üzere geometri verilerine erişim sağlar.

Mesh Geometrisini Okuma

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

Köşe Öğelerine Erişim

Köşe öğeleri, köşe başına veya çokgen başına veri taşır. En yaygın öğeler normal vektörler, UV koordinatları, köşe renkleri ve yumuşatma gruplarıdır:

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

Malzeme Sistemi

Aspose.3D FOSS iki malzeme türünü destekler: LambertMaterial (difüz gölgelendirme) ve PhongMaterial (yansımalı gölgelendirme). Her ikisi de .mtl dosyalarından otomatik olarak yüklenir, kullanırken ObjLoadOptions ile enable_materials = True.

OBJ’den Malzemeleri Okuma

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

Programlı Olarak Bir Malzeme Atama

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

Matematik Yardımcı Araçları

Bu aspose.threed.utilities modül, sahne oluşturma ve inceleme için gereken tüm geometrik matematik tiplerini sağlar.

Dönüşümlerle Çalışma

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

Sınırlayıcı Kutu Hesaplama

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

Animasyon

Aspose.3D FOSS, şuna dayalı bir animasyon modeli sağlar AnimationClip, AnimationNode, KeyFrame, ve KeyframeSequence. Yüklenen dosyalarda (glTF, COLLADA) depolanan animasyon verileri bu nesneler aracılığıyla erişilebilir.

Animasyon Kliplerini Okuma

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

Yükleme ve Kaydetme Seçenekleri

Desteklenen her formatın, ayrıştırma ve serileştirme davranışını kontrol eden ilgili bir seçenek sınıfı vardır.

Kullanım Örnekleri

Örnek 1: OBJ’den STL Formatına Dönüştürme

Bir OBJ dosyasını (malzemelerle birlikte) ikili STL’ye dönüştürün, süreçte ağ istatistiklerini yazdırarak:

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

Örnek 2: Toplu glTF’den GLB’ye Paketleme

Ayrı glTF + doku dosyalarından oluşan bir dizini, kendi içinde bütünleşik GLB ikili dosyaları olarak yeniden kaydedin:

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

Örnek 3: Sahne Grafiği İncelemesi ve Dışa Aktarım Raporu

Bir COLLADA dosyasının sahne grafiğini dolaşın, her ağ için istatistikleri toplayın ve yapılandırılmış bir rapor yazdırın:

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

İpuçları ve En İyi Uygulamalar

Format Seçimi

• glTF 2.0 / GLB malzemeler, animasyonlar ve karmaşık hiyerarşiler içeren sahneler için önerilen değişim formatıdır. Taşınabilirlik için glTF (metin + dış dosyalar) yerine GLB (ikili) tercih edin.
• STL alt tüketici bir dilimleyici, CAD aracı veya yalnızca geometriye ihtiyaç duyan herhangi bir araç olduğunda doğru seçimdir. STL, malzeme veya animasyon verisi taşımaz.
• OBJ geniş çapta desteklenir ve malzeme verisinin eski araçlarla değiş tokuş edilmesi gerektiğinde iyi bir seçimdir. .mtl dosyasını .obj dosyasının yanında tutmayı her zaman unutmayın.

Koordinat Sistemleri

• Farklı uygulamalar farklı el konvansiyonları kullanır. Ayarlayın ObjLoadOptions.flip_coordinate_system = True eğer boru hattınız sol el koordinatlarını bekliyorsa, sağ el koordinat sistemi kullanan araçlardan OBJ dosyaları içe aktarırken ayarlayın; tersine de aynı şekilde.
• Kaynak varlığın eksen düzenini herhangi bir çevirme uygulamadan önce doğrulayın. İki kez çevirme hatalı geometri üretir.

Normalleştirme

• Her zaman ayarlayın ObjLoadOptions.normalize_normal = True alt boru hattı birim normaller beklediğinde (örneğin, normalleri bir gölgeliciye gönderirken veya nokta çarpımı aydınlatma hesaplamaları yaparken). Kötü biçimlendirilmiş OBJ dosyalarından gelen normalize edilmemiş normaller aydınlatma hatalarına neden olur.

Performans

• Dosyaları bir kez yükleyin ve her çıktı formatı için diskte yeniden yüklemek yerine bellek içi sahne grafiğini dönüştürün. Tek bir Scene.from_file() çağrı, ardından birden fazla scene.save() çağrı, tekrarlanan yüklemelerden daha verimlidir.
• Büyük toplu işlemler yaparken, tek bir ObjLoadOptions veya StlSaveOptions örnek oluşturun ve her dosya için yeni bir seçenek nesnesi oluşturmak yerine tüm dosyalar arasında yeniden kullanın.

Hata İşleme

• Sarmak scene.open() ve scene.save() çağrıları try/except güvenilmeyen veya kullanıcı tarafından sağlanan dosyaları işlerken bloklar. İstisna mesajlarında dosya adını raporlayarak toplu işlem hatlarında hata ayıklamayı basitleştirin.

Yaygın Sorunlar

Sık Sorulan Sorular

Hangi Python sürümleri destekleniyor? Python 3.7, 3.8, 3.9, 3.10, 3.11 ve 3.12 tümü desteklenir. Kütüphane, yerel uzantı olmadan saf Python’dir, bu yüzden CPython’un çalıştığı herhangi bir platformda çalışır.

Kütüphanenin dış bağımlılıkları var mı? Hayır. Aspose.3D FOSS for Python yalnızca Python standart kitaplığını kullanır. Tek bir pip install aspose-3d-foss komutla, ek adım olmadan.

FBX destekleniyor mu? FBX tokenleştiricisi uygulanmıştır ve ikili FBX token akışını ayrıştırabilir, ancak tokenleştiricinin üzerindeki sahne grafiği oluşturucu bilinen hatalara sahiptir ve üretim için hazır değildir. Güvenilir üretim kullanımı için OBJ, STL, glTF, COLLADA veya 3MF kullanın.

Ticari bir üründe Aspose.3D FOSS kullanabilir miyim? Evet. Kütüphane MIT lisansı altında yayınlanmıştır; bu lisans, lisans bildiriminin eklenmesi koşuluyla, tescilli ve ticari yazılımlarda telif ücreti ödemeden kullanılmasına izin verir.

Bir hatayı nasıl bildiririm ya da bir format talep ederim? Depoda bir sorun açın. Minimum bir yeniden üretme dosyası ve Python sürümü, işletim sistemi ve kütüphane sürümünü ekleyin. pip show aspose-3d-foss.

API Referans Özeti

Temel Sınıflar

• Scene: 3D sahne için üst düzey kapsayıcı. Giriş noktası: open(), from_file(), ve save().
• Node: Sahne grafiğindeki ağaç düğümü. Taşır entity, transform, global_transform, material, child_nodes, ve name.
• Entity: Düğümlere eklenen nesneler (Mesh, Camera, Light) için temel sınıf.
• Transform: Bir düğüm için yerel uzay konumu, dönüş (Quaternion) ve ölçek.
• GlobalTransform: Tüm üst düğüm dönüşümlerinin birikmesiyle hesaplanan yalnızca okunabilir dünya uzayı dönüşümü.

Geometry

• Mesh: Şu özelliklere sahip çokgen örgü control_points (köşe listesi) ve polygons.
• VertexElementNormal: Köşe başına veya çokgen başına normal vektörler.
• VertexElementUV: Köşe başına UV doku koordinatları.
• VertexElementVertexColor: Köşe başına renk verisi.
• VertexElementSmoothingGroup: Çokgen yumuşatma grup atamaları.

Materyaller

• LambertMaterial: Şu özellikli difüz gölgelendirme modeli diffuse_color ve emissive_color.
• PhongMaterial: Speküler gölgelendirme modeli ekleniyor specular_color ve shininess.

Matematik Yardımcıları (aspose.threed.utilities)

• Vector2: 2D vektör.
• Vector3: 3B çift duyarlıklı vektör.
• Vector4: 4B çift duyarlıklı vektör.
• FVector3: 3B tek duyarlıklı vektör.
• Quaternion: Rotasyon kuaterniyonu ile from_angle_axis() : ve to_matrix().
• Matrix4: 4×4 dönüşüm matrisi.
• BoundingBox: Eksen hizalı sınırlama kutusu ile minimum : ve maximum : köşeler.

Animasyon

• AnimationClip: Animasyon kanalları ve anahtar karelerinden oluşan bir set için adlandırılmış kapsayıcı.
• AnimationNode: Klip içinde düğüm başına animasyon verileri.
• KeyFrame: Zaman ve değer içeren tek bir anahtar kare.
• KeyframeSequence: Tek bir animasyonlu özellik için sıralı anahtar kare dizisi.

Yükleme / Kaydetme Seçenekleri

• ObjLoadOptions: OBJ’ye özgü yükleme ayarları: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL’ye özgü kaydetme ayarları (ikili vs. ASCII modu).

Kameralar ve Işıklar

• Camera: Projeksiyon ayarlarına sahip kamera varlığı, bir. Node.
• Light: Işık kaynağı varlığı, birine takılabilir Node.