विशेषताएँ और कार्यात्मकताएँ

Aspose.3D FOSS for TypeScript एक MIT-लाइसेंस वाला Node.js लाइब्रेरी है जो 3D दृश्यों को लोड करने, निर्माण करने और निर्यात करने के लिए उपयोग किया जाता है। यह पूरी TypeScript टाइप परिभाषाओं के साथ आता है, एकल रनटाइम निर्भरता (xmldom), और छह प्रमुख 3D फ़ाइल फ़ॉर्मैट्स के लिए समर्थन। यह पृष्ठ सभी फीचर क्षेत्रों के लिए मुख्य संदर्भ है और प्रत्येक के लिए चलाने योग्य TypeScript कोड उदाहरण शामिल करता है।.

स्थापना और सेटअप

npm से पैकेज को एक ही कमांड का उपयोग करके इंस्टॉल करें:

npm install @aspose/3d

पैकेज CommonJS को लक्षित करता है और Node.js 18 या बाद के संस्करण की आवश्यकता होती है। इंस्टॉलेशन के बाद, अपने को सत्यापित करें tsconfig.json पूर्ण संगतता के लिए निम्नलिखित कंपाइलर विकल्प शामिल हैं:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

मुख्य को आयात करें Scene क्लास पैकेज रूट से। फ़ॉर्मेट‑विशिष्ट विकल्प क्लासेस को उनके संबंधित सब‑पाथ से इम्पोर्ट किया जाता है:

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

विशेषताएँ और कार्यात्मकताएँ

फ़ॉर्मैट समर्थन

Aspose.3D FOSS for TypeScript छह प्रमुख 3D फ़ाइल फ़ॉर्मेट्स को पढ़ता और लिखता है। लोड करते समय बाइनरी मैजिक नंबरों से फ़ॉर्मेट का पता स्वचालित रूप से लगाया जाता है, इसलिए आपको स्रोत फ़ॉर्मेट को स्पष्ट रूप से निर्दिष्ट करने की आवश्यकता नहीं है।.

सामग्री (materials) के साथ OBJ लोड करना:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
options.flipCoordinateSystem = false;
options.scale = 1.0;
options.normalizeNormal = true;
scene.open('model.obj', options);

GLB (बाइनरी glTF) में सेव करना:

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

const scene = new Scene();
// ... build or load scene content

const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', GltfFormat.getInstance(), opts);

सीन ग्राफ

सभी 3D सामग्री को एक ट्री के रूप में व्यवस्थित किया गया है Node ऑब्जेक्ट्स जो मूल रूप से स्थित हैं scene.rootNode. प्रत्येक नोड एक Entity (एक Mesh, Camera, Light, या अन्य SceneObject) और एक Transform जो इसे उसके पैरेंट के सापेक्ष स्थित करता है।.

मुख्य scene-graph क्लासेज़:

• Scene: शीर्ष-स्तर कंटेनर; रखता है rootNode और animationClips
• Node: एक नामित ट्री नोड जिसके साथ childNodes, entity, transform, और materials
• Entity: संलग्न करने योग्य वस्तुओं के लिए बेस क्लास (Mesh, Camera, Light)
• SceneObject: साझा किया गया बेस क्लास Node और Entity
• A3DObject: रूट बेस क्लास जिसमें name और प्रॉपर्टी बैग
• Transform: स्थानीय अनुवाद, घूर्णन (यूलर और क्वाटरनियन), और स्केल

scene graph को ट्रैवर्स करना:

import { Scene, Node, Mesh } from '@aspose/3d';

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

function visit(node: Node, depth: number = 0): void {
  const indent = '  '.repeat(depth);
  console.log(`${indent}Node: ${node.name}`);
  if (node.entity) {
    console.log(`${indent}  Entity: ${node.entity.constructor.name}`);
  }
  for (const child of node.childNodes) {
    visit(child, depth + 1);
  }
}

visit(scene.rootNode);

प्रोग्रामेटिक रूप से एक सीन पदानुक्रम बनाना:

import { Scene, Node } from '@aspose/3d';

const scene = new Scene();
const parent = scene.rootNode.createChildNode('chassis');
const wheel = parent.createChildNode('wheel_fl');
wheel.transform.translation.set(0.9, -0.3, 1.4);

ज्यामिति और Mesh

Mesh मुख्य ज्यामिति प्रकार है। यह विस्तारित करता है Geometry और नियंत्रण बिंदु (वर्टिसेज), पॉलीगॉन इंडेक्स, तथा सामान्य, UVs, और वर्टेक्स रंगों के लिए वर्टेक्स तत्व उजागर करता है।.

मुख्य ज्यामिति वर्ग:

• Mesh: पॉलीगॉन मेष जिसमें controlPoints और polygonCount
• Geometry: vertex-element प्रबंधन के साथ base class
• VertexElementNormal: प्रति-वर्टेक्स या प्रति-पॉलीगॉन-वर्टेक्स normals
• VertexElementUV: टेक्सचर कोऑर्डिनेट्स (एक या अधिक UV चैनल्स)
• VertexElementVertexColor: प्रति-वर्टेक्स कलर डेटा
• MappingMode: नियंत्रित करता है कि एलिमेंट डेटा पॉलीगॉन पर कैसे मैप होता है (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: इंडेक्सिंग स्ट्रैटेजी को नियंत्रित करता है (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: वर्टेक्स एलिमेंट के semantic की पहचान करता है
• TextureMapping: टेक्सचर चैनल enumeration

लोड किए गए सीन से मेष डेटा पढ़ना:

import { Scene, Mesh, VertexElementType } from '@aspose/3d';

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

for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices, ${mesh.polygonCount} polygons`);

    const normals = mesh.getElement(VertexElementType.NORMAL);
    if (normals) {
      console.log(`  Normal mapping: ${normals.mappingMode}`);
    }
  }
}

मैटेरियल सिस्टम

Aspose.3D FOSS for TypeScript तीन सामग्री प्रकारों का समर्थन करता है जो लेगेसी फ़ॉन्ग शेडिंग से लेकर फिज़िकली-आधारित रेंडरिंग तक पूरी रेंज को कवर करते हैं:

• LambertMaterial: डिफ्यूज़ कलर और एंबिएंट कलर; सरल OBJ/DAE मैटीरियल्स से मैप होता है
• PhongMaterial: स्पेक्युलर कलर, शाइनिनेस, और एमिसिव जोड़ता है; डिफ़ॉल्ट OBJ मैटीरियल टाइप
• PbrMaterial: फिज़िकली-बेस्ड रफ़नेस/मेटैलिक मॉडल; glTF 2.0 इम्पोर्ट और एक्सपोर्ट के लिए उपयोग किया जाता है

लोड किए गए OBJ सीन से मैटेरियल पढ़ना:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.open('model.obj', options);

for (const node of scene.rootNode.childNodes) {
  for (const mat of node.materials) {
    if (mat instanceof PhongMaterial) {
      const phong = mat as PhongMaterial;
      console.log(`  Phong: diffuse=${JSON.stringify(phong.diffuseColor)}, shininess=${phong.shininess}`);
    } else if (mat instanceof LambertMaterial) {
      console.log(`  Lambert: diffuse=${JSON.stringify((mat as LambertMaterial).diffuseColor)}`);
    }
  }
}

glTF सीन बनाते समय PBR मैटेरियल लागू करना:

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

const scene = new Scene();
const node = scene.rootNode.createChildNode('sphere');
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.8, 0.2, 0.2);   // red-tinted albedo; albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.5;
node.material = mat;

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

गणितीय उपयोगिताएँ

लाइब्रेरी एक पूर्ण सेट 3D गणित प्रकारों के साथ आती है, सभी पूरी तरह टाइप्ड हैं:

• Vector3: 3-घटक वेक्टर; समर्थन करता है minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: समानुपाती निर्देशांक के लिए 4-घटक वेक्टर
• Matrix4: 4×4 रूपांतरण मैट्रिक्स जिसमें concatenate(), transpose, decompose, setTRS
• Quaternion: घूर्णन क्वाटरनियन जिसमें fromEulerAngle() (स्थैतिक, एकवचन), eulerAngles() (इंस्टेंस मेथड), slerp(), normalize()
• BoundingBox: अक्ष-समरेखित बाउंडिंग बॉक्स जिसमें minimum, maximum, center, size, merge
• FVector3: सिंगल-प्रिसीजन वैरिएंट ऑफ Vector3 वर्टेक्स एलिमेंट डेटा में उपयोग किया जाता है

मेश वर्टिसेज़ से बाउंडिंग बॉक्स की गणना करना:

import { Scene, Mesh, Vector3, BoundingBox } from '@aspose/3d';

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

let box = new BoundingBox();
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    for (const pt of (node.entity as Mesh).controlPoints) {
      box.merge(new Vector3(pt.x, pt.y, pt.z));
    }
  }
}
console.log('Center:', box.center);
console.log('Extents:', box.size);

यूलर एंगल्स से ट्रांसफ़ॉर्म बनाना:

import { Quaternion, Vector3, Matrix4 } from '@aspose/3d';

const rot = Quaternion.fromEulerAngle(0, Math.PI / 4, 0); // 45° around Y
const mat = new Matrix4();
mat.setTRS(new Vector3(0, 0, 0), rot, new Vector3(1, 1, 1));

एनिमेशन सिस्टम

एनिमेशन API क्लिप्स, नोड्स, चैनल्स, और कीफ़्रेम सीक्वेंसेज़ को मॉडल करता है:

• AnimationClip: एनीमेशन नोड्स का नामित संग्रह; के माध्यम से एक्सेस किया जाता है scene.animationClips; उजागर करता है animations: AnimationNode[]
• AnimationNode:नामित समूह BindPoints; द्वारा निर्मित clip.createAnimationNode(name), द्वारा अभिगमित clip.animations
• BindPoint: एक को बाँधता है AnimationNode एक दृश्य वस्तु की विशिष्ट प्रॉपर्टी से; उजागर करता है property और channelsCount
• AnimationChannel: विस्तारित करता है KeyframeSequence; एक अलग रखता है keyframeSequence; द्वारा अभिगमित bindPoint.getChannel(name)
• KeyFrame: एक एकल समय/मान जोड़ी; प्रति-कीफ़्रेम ले जाता है interpolation: Interpolation
• KeyframeSequence: क्रमबद्ध सूची KeyFrame ऑब्जेक्ट्स के माध्यम से keyFrames; है preBehavior और postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: class with type: ExtrapolationType और repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

लोड किए गए सीन से एनीमेशन डेटा पढ़ना:

import { Scene, AnimationNode, BindPoint } from '@aspose/3d';

const scene = new Scene();
scene.open('animated.dae');   // COLLADA animation import is supported

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.animations) {          // clip.animations, not clip.nodes
    console.log(`  AnimationNode: ${animNode.name}`);
    for (const bp of animNode.bindPoints) {           // animNode.bindPoints, not animNode.channels
      console.log(`  BindPoint: property="${bp.property.name}", channels=${bp.channelsCount}`);
    }
  }
}

स्ट्रीम और बफ़र समर्थन

उपयोग करें scene.openFromBuffer() को एक 3D सीन सीधे इन-मेमोरी से लोड करने के लिए Buffer. यह सर्वरलेस फ़ंक्शन्स, स्ट्रीमिंग पाइपलाइन्स, और HTTP के माध्यम से प्राप्त एसेट्स को डिस्क पर लिखे बिना प्रोसेस करने के लिए अनुशंसित पैटर्न है।.

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

// Load file into memory, then parse from buffer
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);

for (const node of scene.rootNode.childNodes) {
  if (node.entity) {
    console.log(node.name, node.entity.constructor.name);
  }
}

बफ़र से लोड करते समय बाइनरी मैजिक नंबरों से फ़ॉर्मेट का ऑटो-डिटेक्शन लागू होता है, इसलिए GLB, STL बाइनरी, और 3MF फ़ाइलें फ़ॉर्मेट पैरामीटर निर्दिष्ट किए बिना पहचानी जाती हैं।.

उपयोग के उदाहरण

उदाहरण 1: OBJ लोड करें और GLB में एक्सपोर्ट करें

यह उदाहरण सामग्री के साथ एक Wavefront OBJ फ़ाइल लोड करता है, फिर सीन को वेब और गेम इंजन उपयोग के लिए उपयुक्त बाइनरी glTF (GLB) फ़ाइल के रूप में पुनः एक्सपोर्ट करता है।.

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

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();

  const loadOpts = new ObjLoadOptions();
  loadOpts.enableMaterials = true;
  loadOpts.flipCoordinateSystem = false;
  loadOpts.normalizeNormal = true;
  scene.open(inputPath, loadOpts);

  // Report what was loaded
  for (const node of scene.rootNode.childNodes) {
    if (node.entity) {
      console.log(`Loaded: ${node.name} (${node.entity.constructor.name})`);
    }
  }

  const saveOpts = new GltfSaveOptions();
  saveOpts.binaryMode = true; // write .glb instead of .gltf + .bin
  scene.save(outputPath, GltfFormat.getInstance(), saveOpts);

  console.log(`Exported GLB to: ${outputPath}`);
}

convertObjToGlb('input.obj', 'output.glb');

उदाहरण 2: नॉर्मल वैलिडेशन के साथ राउंड-ट्रिप STL

यह उदाहरण एक बाइनरी STL फ़ाइल लोड करता है, प्रति-वर्टेक्स नॉर्मल जानकारी प्रिंट करता है, फिर सीन को ASCII STL के रूप में पुनः एक्सपोर्ट करता है और राउंडट्रिप की पुष्टि करता है।.

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

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

let totalPolygons = 0;
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    totalPolygons += mesh.polygonCount;

    const normElem = mesh.getElement(VertexElementType.NORMAL) as VertexElementNormal | null;
    if (normElem) {
      console.log(`  Normals: ${normElem.data.length} entries, mapping=${normElem.mappingMode}`);
    }
  }
}
console.log(`Total polygons: ${totalPolygons}`);

// Re-export as ASCII STL
const saveOpts = new StlSaveOptions();
saveOpts.binaryMode = false; // ASCII output
scene.save('output_ascii.stl', saveOpts);

उदाहरण 3: प्रोग्रामेटिक रूप से एक सीन बनाएं और इसे glTF के रूप में सहेजें

यह उदाहरण शून्य से एक PBR सामग्री के साथ सीन बनाता है और इसे JSON glTF फ़ाइल के रूप में सहेजता है।.

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

const scene = new Scene();
const node = scene.rootNode.createChildNode('floor');

// Build a simple quad mesh (two triangles)
// controlPoints are Vector4 (x, y, z, w) where w=1 for positions
const mesh = new Mesh();
mesh.controlPoints.push(
  new Vector4(-1, 0, -1, 1),
  new Vector4( 1, 0, -1, 1),
  new Vector4( 1, 0,  1, 1),
  new Vector4(-1, 0,  1, 1),
);
mesh.createPolygon([0, 1, 2]);
mesh.createPolygon([0, 2, 3]);
node.entity = mesh;

// Apply a PBR material
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.6, 0.6, 0.6);   // albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.8;
node.material = mat;

// Save as JSON glTF
const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('floor.gltf', GltfFormat.getInstance(), opts);
console.log('Scene written to floor.gltf');

टिप्स और सर्वोत्तम प्रथाएँ

• उपयोग करें ObjLoadOptions.enableMaterials = true जब भी आपको .mtl फ़ाइलों से सामग्री डेटा की आवश्यकता हो। इसके बिना, प्रत्येक नोड पर सामग्री सूची खाली होगी।.
• पसंद करें binaryMode = true GLB के लिए वेब या गेम इंजन के लिए एसेट्स बनाते समय। बाइनरी GLB एक एकल स्व-निहित फ़ाइल है और ब्राउज़रों और इंजनों में JSON + .bin विभाजन की तुलना में तेज़ लोड होती है।.
• उपयोग करें openFromBuffer() सर्वरलेस वातावरण में अस्थायी फ़ाइल I/O से बचने के लिए। एसेट को प्राप्त करें, पास करें Buffer सीधे, और आउटपुट को एक स्ट्रीम या अन्य बफ़र में लिखें।.
• जाँचें node.entity कास्ट करने से पहले: सभी नोड्स में इकाई नहीं होती। हमेशा एक के साथ गार्ड करें instanceof पहुँचने से पहले जाँचें Mesh-विशिष्ट गुण जैसे controlPoints.
• Set normalizeNormal = true में ObjLoadOptions जब आपके स्रोत OBJ फ़ाइलें अविश्वसनीय स्रोतों से आती हैं। यह विकृत नॉर्मल्स को डाउनस्ट्रीम रेंडरिंग या वैधता चरणों में प्रसारित होने से रोकता है।.
• रखें strict: true tsconfig.json में: लाइब्रेरी … के साथ लिखी गई है noImplicitAny और strictNullChecks. अक्षम करना strict वास्तविक प्रकार त्रुटियों को छुपाता है और टाइप्ड API के मूल्य को नष्ट करता है।.
• के माध्यम से पार करें childNodes, इंडेक्स लूप नहीं: यह childNodes प्रॉपर्टी एक इटेरेबल लौटाती है; आगे की संगतता के लिए संख्यात्मक इंडेक्सिंग पर निर्भरता से बचें।.

सामान्य समस्याएँ

अक्सर पूछे जाने वाले प्रश्न

क्या लाइब्रेरी को कोई नेटिव ऐडऑन या सिस्टम पैकेज की आवश्यकता है? नहीं। Aspose.3D FOSS for TypeScript में एक ही रनटाइम निर्भरता है: xmldom, जो शुद्ध जावास्क्रिप्ट है और npm द्वारा स्वचालित रूप से स्थापित होती है। कोई नहीं .node नेटिव ऐडऑन और कोई सिस्टम पैकेज इंस्टॉल करने की आवश्यकता नहीं।.

कौन से Node.js संस्करण समर्थित हैं? Node.js 18, 20, और 22 LTS। लाइब्रेरी CommonJS आउटपुट को लक्षित करती है और आंतरिक रूप से ES2020 भाषा सुविधाओं का उपयोग करती है।.

क्या मैं लाइब्रेरी को ब्राउज़र बंडल (webpack/esbuild) में उपयोग कर सकता हूँ? लाइब्रेरी Node.js को लक्षित करती है और Node.js का उपयोग करती है fs और Buffer API। ब्राउज़र बंडलिंग आधिकारिक रूप से समर्थित नहीं है। ब्राउज़र उपयोग के लिए, सीन को सर्वर‑साइड लोड करें और परिणाम (उदाहरण के लिए, GLB के रूप में) क्लाइंट को भेजें।.

के बीच अंतर क्या है GltfSaveOptions.binaryMode = true और false? binaryMode = false एक उत्पन्न करता है .gltf JSON फ़ाइल साथ में एक अलग .bin बाइनरी बफ़र साइडकार।. binaryMode = true एक एकल स्व-समाहित उत्पन्न करता है .glb फ़ाइल। उपयोग करें true उत्पादन एसेट डिलीवरी के लिए।.

क्या मैं डिस्क पर सहेजे बिना HTTP प्रतिक्रिया से फ़ाइल लोड कर सकता हूँ? हाँ। प्रतिक्रिया को एक के रूप में प्राप्त करें Buffer (उदाहरण के लिए, उपयोग करके node-fetch या अंतर्निहित fetch Node 18+ में), फिर कॉल करें scene.openFromBuffer(buffer, options).

क्या FBX समर्थन पूर्ण है? नहीं। लाइब्रेरी में FBX इम्पोर्टर और एक्सपोर्टर क्लासेज मौजूद हैं, लेकिन FBX को इसमें जोड़ा नहीं गया है Scene.open() या Scene.save() ऑटो-डिटेक्शन। कॉलिंग scene.open('file.fbx') FBX इम्पोर्टर को आह्वान नहीं करेगा; फ़ाइल को STL फ़ॉलबैक पाथ द्वारा संभाला जाएगा। यदि आपको FBX I/O चाहिए तो FBX-विशिष्ट इम्पोर्टर/एक्सपोर्टर क्लासेस को सीधे उपयोग करें। ऊपर दिए गए फ़ॉर्मेट सपोर्ट टेबल को देखें जो FBX को चिह्नित करता है No*.

क्या लाइब्रेरी TypeScript 4.x को सपोर्ट करती है? TypeScript 5.0+ की सिफारिश की जाती है। TypeScript 4.7+ व्यावहारिक रूप से काम करना चाहिए, लेकिन लाइब्रेरी को 5.0+ के खिलाफ परीक्षण किया गया है और लिखा गया है।.

API रेफ़रेंस सारांश