پشتیبانی از فرمت‌های سه‌بعدی

Aspose.3D FOSS برای TypeScript هفت فرمت اصلی فایل 3D را می‌خواند و می‌نویسد. تشخیص فرمت به‌صورت خودکار هنگام بارگذاری انجام می‌شود: کتابخانه اعداد جادویی باینری را بررسی می‌کند، بنابراین نیازی به مشخص کردن فرمت منبع ندارید. کلاس‌های گزینه‌های مخصوص هر فرمت از زیرمسیرهای بستهٔ @aspose/3d بسته.

فرمت‌های پشتیبانی‌شده

OBJ (Wavefront)

OBJ هر دو واردات و صادرات را در @aspose/3d. هنگام ذخیره به‌صورت OBJ، کتابخانه مواد (.mtl) به‌صورت خودکار در کنار .obj فایل. استفاده کنید ObjLoadOptions برای کنترل بارگذاری مواد و رفتار سیستم مختصات.

گزینه‌های کلیدی برای ObjLoadOptions:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

برای تبدیل یک OBJ به هر فرمت قابل نوشتن، آن را بارگذاری کنید و فراخوانی کنید scene.save() با کلاس فرمت هدف.

glTF و GLB

glTF 2.0 فرمت تبادل پیشنهادی برای استفاده در وب و موتورهای بازی است. کتابخانه از همان GltfFormat کلاس برای هر دو .gltf (JSON + sidecar) و .glb (binary, self-contained) خروجی. با استفاده از … بین آن‌ها جابجا شوید. GltfSaveOptions.binaryMode.

بارگذاری glTF یا GLB:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

صادرات به صورت JSON glTF (.gltf + .bin):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.fbx');

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

صادرات به صورت باینری GLB (.glb):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

استفاده کنید binaryMode = true برای تحویل دارایی در محیط تولید. یک .glb در مرورگرها و موتورها سریع‌تر بارگذاری می‌شود نسبت به جفت متن + باینری جداگانه.

STL

STL یک فرمت مش مثلثی است که در CAD و چاپ سه‌بعدی استفاده می‌شود. هر دو نوع باینری و ASCII STL برای ورودی و خروجی پشتیبانی می‌شوند. StlSaveOptions.binaryMode کنترل می‌کند که خروجی باینری (فشرده) باشد یا ASCII (قابل خواندن برای انسان).

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

STL فقط هندسه مثلثی و نرمال‌های راس را ذخیره می‌کند. داده‌های مواد و UV در STL حفظ نمی‌شوند.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

import { Scene } from '@aspose/3d';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

هشدار: کلاس‌های واردکننده و صادرکننده FBX (FbxImporter, FbxExporter) در کتابخانه موجود هستند، اما تشخیص خودکار فرمت FBX اتصال داده نشده به scene.open() یا scene.save(). scene.open('file.fbx') فراخوانی scene.save('output.fbx', opts) فایل‌صادرکننده FBX را فراخوانی نخواهد کرد. جدول پشتیبانی فرمت در بالا FBX را به عنوان No* به این دلیل. برای واردات و صادرات کامل از GLB یا COLLADA استفاده کنید scene.open() / scene.save().

COLLADA (DAE)

COLLADA یک فرمت تبادل مبتنی بر XML است که توسط طیف گسترده‌ای از ابزارهای DCC (Blender، Maya، Cinema 4D) پشتیبانی می‌شود. کتابخانه از xmldom وابستگی برای تجزیه XML؛ به‌صورت خودکار همراه با npm install @aspose/3d.

import { Scene } from '@aspose/3d';
import { ColladaSaveOptions } from '@aspose/3d/formats/collada';

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

فایل‌های COLLADA ممکن است شامل فرادادهٔ مقیاس‌گذاری واحد (<unit> عنصر). کتابخانه به‌صورت خودکار تبدیل واحد را هنگام بارگذاری اعمال می‌کند.

تشخیص خودکار فرمت

هنگام بارگذاری از مسیر فایل، کتابخانه سعی می‌کند فرمت را از اعداد جادویی باینری شناسایی کند قبل از اینکه به پسوند فایل بازگردد. این به این معنی است که می‌توانید یک فایل GLB به نام .bin یا یک فایل STL به نام .model بدون اینکه فرمت را به‌صورت صریح مشخص کنید.

هنگام بارگذاری از یک Buffer با scene.openFromBuffer(), تشخیص magic-number مکانیزم اصلی است:

import { Scene } from '@aspose/3d';
import * as fs from 'fs';

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

قالب‌های دارای magic-numberهای قابل اعتماد: GLB (glTF), باینری STL (سرآیند 80 بایتی + تعداد مثلث‌ها)، 3MF (ZIP magic PK). OBJ و COLLADA مبتنی بر متن هستند و از پسوند فایل یا از طریق کلاس گزینه‌هایی که می‌فرستید شناسایی می‌شوند.

نکات

• OBJ هر دو عملیات واردات و صادرات را پشتیبانی می‌کند: هنگام ذخیره به‌صورت OBJ، .mtl فایل material به‌صورت خودکار در کنار .obj فایل.
• از GLB برای تحویل وب استفاده کنید:قالب باینری خودکفا از بروز مشکلات CORS با .bin ساید‌کارها و سریع‌تر در رندررهای WebGL بارگذاری می‌شود.
• گزینه‌های مخصوص به قالب را پاس کنید: عمومی scene.open(path) برای اکثر قالب‌ها کار می‌کند، اما عبور دادن کلاس گزینه‌های لودر، رفتار مخصوص به قالب را فعال می‌سازد، مانند بارگذاری متریال OBJ یا نرمال‌سازی مختصات STL.
• xmldom برای COLLADA لازم است: به‌صورت خودکار نصب می‌شود. آن را به peerDependencies یا سعی نکنید آن را حذف کنید؛ خواننده COLLADA به‌طور مستقیم از آن استفاده می‌کند.

مشکلات رایج

همچنین ببینید

• ویژگی‌ها و عملکردها: گراف صحنه، مش، مواد، انیمیشن و APIهای ریاضی.
• گراف صحنه: ساخت و پیمایش درخت گره.
• چگونه یک 3D Mesh را به‌صورت برنامه‌نویسی ایجاد کنیم.