Aspose.3D FOSS
Python
개발자 가이드
포맷 지원

포맷 지원

Aspose.3D FOSS for Python은 단일 메모리 내 씬 표현을 사용하여 7개의 3D 포맷을 읽고 쓸 수 있습니다. 라이브러리는 각 포맷을 공통 Scene 로드 시 객체로 변환하고 저장 시 해당 객체를 대상 포맷으로 직렬화합니다. 이는 OBJ에서 로드된 씬을 중간 변환 단계 없이 바로 glTF로 저장할 수 있음을 의미합니다.

지원되는 포맷

포맷확장자읽기쓰기옵션 클래스참고
Wavefront OBJ.obj예예ObjLoadOptions.mtl 재질 로딩 지원
STL (binary).stl예예StlSaveOptionsBinary 및 ASCII 읽기; 저장은 기본적으로 binary
STL (ASCII).stl예예StlSaveOptions왕복 검증 완료
glTF 2.0.gltf예예GltfSaveOptions전체 씬 그래프, 재질 및 애니메이션이 보존됩니다
GLB (binary glTF).glb예예GltfSaveOptions단일 파일 바이너리 컨테이너
COLLADA.dae예예ColladaLoadOptions / ColladaSaveOptions장면 계층 구조 및 재료
3MF.3mf예예ThreeMfSaveOptions적층 제조 형식
FBX.fbx부분아니오N/ATokenizer 작동 중; 전체 파서는 진행 중프로덕션 준비가 되지 않음)

OBJ 포맷

Wavefront OBJ는 정적 메쉬에 가장 널리 지원되는 교환 포맷입니다. Aspose.3D FOSS는 기하학(정점, 법선, UV 좌표 및 다각형 면)을 로드하고 선택적으로 동반 .mtl 재질 파일.

ObjLoadOptions

속성유형기본값설명
enable_materialsboolTrue구문 분석 .mtl OBJ 헤더가 참조하는 파일
flip_coordinate_systemboolFalseY-업 오른손 좌표계를 Z-업 오른손 좌표계로 변환
normalize_normalboolTrue가져온 모든 표면 법선을 단위 길이로 정규화
scalefloat1.0모든 정점 위치에 적용되는 균일 스케일 팩터

OBJ 파일 로드 

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

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

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

print(f"Top-level nodes: {len(scene.root_node.child_nodes)}")

OBJ 저장 

scene.save("output.obj")

OBJ 내보내기는 정점 위치와 폴리곤 면을 기록합니다. 장면에 포함된 경우 LambertMaterial 또는 PhongMaterial 객체가 있으면, 라이브러리는 보조 .mtl 파일을 자동으로 생성합니다.

STL 형식

STL (STereoLithography)은 삼각형 메쉬를 인덱스가 없는 면 리스트로 저장합니다. 읽기 시 바이너리와 ASCII 두 가지 변형을 모두 지원하며, 저장 시 라이브러리는 기본적으로 바이너리를 사용합니다.

StlSaveOptions

StlSaveOptions 필수 필드가 없습니다. 이를 인스턴스화하여 전달합니다. scene.save():

from aspose.threed.formats import StlSaveOptions

opts = StlSaveOptions()
scene.save("output.stl", opts)

라운드트립 예제 

from aspose.threed import Scene

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

##Inspect
for node in scene.root_node.child_nodes:
    if node.entity:
        print(f"{node.name}: {len(node.entity.control_points)} vertices")

##Save
scene.save("roundtrip.stl")

STL은 삼각형 기하학만 저장하며, 면 법선 외의 노멀, UV 좌표, 재질, 계층 구조를 저장하지 않습니다. 장면에 사각형이나 고차 다각형이 포함되어 있으면 저장 시 자동으로 삼각형으로 분할됩니다.

glTF / GLB 포맷

glTF 2.0은 최신 3D 교환을 위한 권장 포맷입니다. 전체 씬 그래프(노드 계층 구조, 명명된 노드, 변환), 재질을 보존합니다 (LambertMaterial, PhongMaterial → PBR 변환), 그리고 애니메이션 클립을 보존합니다. GLB는 단일 파일 바이너리 컨테이너 변형입니다.

GltfSaveOptions 

from aspose.threed.formats import GltfSaveOptions

opts = GltfSaveOptions()
scene.save("output.gltf", opts)   # JSON + external .bin
scene.save("output.glb",  opts)   # Self-contained binary

재질 지원

Aspose.3D FOSS 재료는 glTF에 매핑됩니다 pbrMetallicRoughness 내보내기 시:

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

scene = Scene()
node = scene.root_node.create_child_node("object")

mat = PhongMaterial()
mat.diffuse_color  = Vector3(0.8, 0.2, 0.2)   # red
mat.specular_color = Vector3(1.0, 1.0, 1.0)
mat.shininess = 50.0
node.material = mat

scene.save("colored.gltf")

glTF 출력 검증 

import json

with open("output.gltf") as f:
    data = json.load(f)

print(f"Asset version : {data['asset']['version']}")
print(f"Nodes         : {len(data.get('nodes', []))}")
print(f"Meshes        : {len(data.get('meshes', []))}")

COLLADA 포맷

COLLADA (.dae)는 XML 기반 포맷으로, 씬 계층 구조, 재질, 다중 UV 채널 및 스켈레톤 애니메이션을 지원합니다. Aspose.3D FOSS는 전체 노드 트리와 재질 정의를 읽고 씁니다.

from aspose.threed import Scene

##Load a COLLADA file
scene = Scene.from_file("model.dae")

##Inspect top-level nodes
for node in scene.root_node.child_nodes:
    print(f"  {node.name}")

##Save back to COLLADA
scene.save("output.dae")

COLLADA는 명명된 노드와 재질을 가진 계층 구조를 데이터 손실 없이 라운드트립해야 할 때 좋은 선택입니다.

3MF Format

3MF (3D Manufacturing Format) targets additive manufacturing (3D printing) workflows. It stores triangle geometry, colour, and print-specific metadata in a ZIP-based container.

from aspose.threed import Scene
from aspose.threed.formats import ThreeMfSaveOptions

scene = Scene.from_file("part.stl")   # Load from STL
opts  = ThreeMfSaveOptions()
scene.save("part.3mf", opts)          # Write as 3MF

3MF is the recommended export format when targeting slicer software (Cura, PrusaSlicer, Bambu Studio, etc.).

FBX 포맷

상태: 진행 중 (프로덕션 준비 완료 아님).

FBX (.fbx) 지원은 Aspose.3D FOSS에서 현재 토크나이저 단계에 있습니다. 바이너리 FBX 토크나이저는 파일 구조를 파싱할 수 있지만, 전체 노드, 메시 및 재질 파서는 알려진 버그가 있으며 완전하지 않습니다. FBX 읽기 결과는 실험적인 것으로 간주해야 합니다.

이번 릴리스에서는 프로덕션 파이프라인에서 FBX를 사용하지 마세요. 소스 데이터가 FBX 형식이라면, Blender 또는 FBX Review를 사용해 먼저 glTF 또는 OBJ로 변환한 후 Aspose.3D FOSS로 로드하십시오.

FBX 쓰기는 지원되지 않습니다.

포맷 자동 감지

Scene.from_file() 그리고 scene.open() 파일 확장자를 사용하고, 가능한 경우 파일 헤더의 매직 바이트를 이용해 형식을 자동으로 감지합니다:

from aspose.threed import Scene

##The library detects each format without being told explicitly
scene_obj  = Scene.from_file("model.obj")
scene_glb  = Scene.from_file("model.glb")
scene_stl  = Scene.from_file("model.stl")
scene_dae  = Scene.from_file("model.dae")
scene_3mf  = Scene.from_file("model.3mf")

확장자가 없거나 모호한 경우, 라이브러리는 헤더 검사(매직 바이트)로 대체합니다. 지원되지 않거나 인식되지 않는 파일은 예외를 발생시킵니다 IOError 설명적인 메시지를 포함합니다.

팁 및 모범 사례

  • 현대 파이프라인에서는 glTF 또는 GLB를 사용하십시오. glTF는 전체 씬 그래프, 재질 및 애니메이션 데이터를 보존합니다. 게임 엔진 및 웹 뷰어와의 교환을 위한 가장 완전한 포맷입니다.
  • 최대 호환성을 위해 OBJ를 사용하십시오. OBJ는 사실상 모든 3D 툴에서 지원됩니다. 정적 메시에만 제한되지만 매우 휴대성이 뛰어납니다.
  • 인쇄에는 3MF를 사용하세요. 3MF carries colour, orientation hints, and print settings that STL cannot express.
  • FBX는 프로덕션 준비가 될 때까지 사용을 피하세요. 전체 FBX 파싱이 완료된 버전에 대한 릴리스 노트를 확인하세요.
  • 저장 확장자를 포맷에 맞추세요. a를 전달하지 마세요. .gltf binary GLB를 원할 때 확장자를 전달하지 마세요; use .glb 명시적으로. 확장자는 어떤 직렬 변환기를 사용할지 결정합니다.
  • 폴리곤 호환성을 확인하십시오. STL 및 3MF는 삼각형이 필요합니다. 사각형과 N-곤은 저장 시 자동으로 삼각형화되지만, 정점 수가 증가합니다. 삼각형화를 제어해야 하는 경우, call mesh.triangulate() 저장하기 전에.
 한국어