{"_id":"@algoz098/3mf-pr-js","name":"@algoz098/3mf-pr-js","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@algoz098/3mf-pr-js","version":"0.1.0","description":"Biblioteca em TypeScript para geração de arquivos 3MF (3D Manufacturing Format)","license":"MIT","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./generator":{"types":"./dist/generator.d.ts","default":"./dist/generator.js"}},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","dev:test":"vitest","clean":"rm -rf dist"},"engines":{"node":">=18"},"dependencies":{"@tensorgrad/lib3mf":"^0.1.11","ajv":"^8.17.1","jszip":"^3.10.1","uuid":"^9.0.1","xmlbuilder2":"^3.1.1"},"devDependencies":{"@types/node":"^20.11.30","@types/uuid":"^9.0.7","pngjs":"^7.0.0","typescript":"^5.6.3","vitest":"^1.6.0"},"_id":"@algoz098/3mf-pr-js@0.1.0","gitHead":"7b3c60429396809b1a4d9e6f99d6e7f135cea85b","_nodeVersion":"24.7.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-WBtgISFNrzYSsE6b478TQdV26M9AdVHBf59iCPmlq+5G+fvhVX0eCIqF6HFDQvnZONV0lOCQZo5Vy2p+1Q8Q9A==","shasum":"d31296c916a49ac4f5c11a85619ff32d109c9f15","tarball":"https://registry.npmjs.org/@algoz098/3mf-pr-js/-/3mf-pr-js-0.1.0.tgz","fileCount":18,"unpackedSize":95497,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAndyowk9vuoeIYhhm/hNLuPD6w2fBxr+biS6UfjTEFoAiAMiPYuc48Tr/vg8tO+vAqIp6pMSr6xPGgX28h2Y/qoqQ=="}]},"_npmUser":{"name":"algoz098","email":"algoz098@gmail.com"},"directories":{},"maintainers":[{"name":"algoz098","email":"algoz098@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/3mf-pr-js_0.1.0_1766022031704_0.663104619287985"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-18T01:40:31.603Z","0.1.0":"2025-12-18T01:40:31.876Z","modified":"2025-12-18T01:40:32.187Z"},"maintainers":[{"name":"algoz098","email":"algoz098@gmail.com"}],"description":"Biblioteca em TypeScript para geração de arquivos 3MF (3D Manufacturing Format)","license":"MIT","readme":"# 3mf-pr-js\n\n\n\n**Biblioteca TypeScript/JavaScript para geração de arquivos 3MF (3D Manufacturing Format)**\n\n[](https://www.npmjs.com/package/3mf-pr-js)\n[](https://opensource.org/licenses/MIT)\n[](https://www.typescriptlang.org/)\n[](https://nodejs.org)\n\nBiblioteca moderna e completa para criar arquivos 3MF production-ready compatíveis com Bambu Studio, PrusaSlicer e outros slicers profissionais.\n\n[Início Rápido](#-instalação) • [Documentação](#-documentação) • [Exemplos](#-exemplos) • [API](#-api-reference) • [Contribuir](#-contribuindo)\n\n
\n\n---\n\n## 📑 Índice\n\n- [Características](#-características)\n- [Instalação](#-instalação)\n- [Uso Rápido](#-uso-rápido)\n- [Recursos Avançados](#-recursos-avançados)\n- [Documentação](#-documentação)\n- [Exemplos](#-exemplos)\n- [Testes](#-testes)\n- [API Reference](#-api-reference)\n- [Compatibilidade](#-compatibilidade)\n- [Contribuindo](#-contribuindo)\n- [Licença](#-licença)\n\n## 🚀 Características\n\n### Core 3MF\n- ✅ **Especificação completa v1.3** - Suporte total à especificação 3MF Core\n- ✅ **Geometria 3D** - Malhas triangulares com vértices e triângulos\n- ✅ **Transformações** - Matrizes 4x3 para posicionamento e rotação\n- ✅ **Unidades flexíveis** - millimeter, inch, micron, centimeter, foot, meter\n- ✅ **Metadados** - Title, Designer, Author, Description e mais\n\n### Extensões\n- ✅ **Production Extension** - UUIDs, multifile, assemblies, partnumbers\n- ✅ **Materials Extension** - Color groups, texturas, composite e multi-materials\n- ✅ **Triangle Sets** - Agrupamento lógico de triângulos\n\n### Materiais\n- ✅ **Base Materials** - Múltiplos conjuntos com cores RGBA\n- ✅ **Color Groups** - Paletas de cores reutilizáveis\n- ✅ **Texturas** - PNG/JPEG com coordenadas UV\n- ✅ **Composite Materials** - Misturas ponderadas de materiais\n- ✅ **Multi-Materials** - Combinação de múltiplos recursos\n- ✅ **Por triângulo** - Override de materiais por face\n\n### Validação\n- ✅ **JSON Schema** - Validação de entrada com AJV\n- ✅ **Geometria** - Winding order e manifold checks\n- ✅ **lib3mf** - Validação estrutural e OPC via SDK oficial\n- ✅ **Relatórios detalhados** - Erros e warnings explicativos\n\n### Otimização de Memória\n- ✅ **TypedArrays** - Float32Array/Uint32Array para redução de 90%+ memória\n- ✅ **Deduplicação de vértices** - Remove vértices duplicados automaticamente\n- ✅ **Geometry pooling** - Reutiliza meshes idênticas\n- ✅ **Estimativa de memória** - Análise de uso em tempo real\n- ✅ **Suporte a modelos grandes** - Processa modelos 10-100x maiores\n\n### Developer Experience\n- ✅ **API simples** - Função de alto nível `generate3MF()` ou API fluente `Model`\n- ✅ **TypeScript nativo** - Tipos completos e autocomplete\n- ✅ **Thumbnails flexíveis** - PNG/JPEG em `/Thumbnails` ou `/Metadata`\n- ✅ **Testado** - 76 testes cobrindo todos os recursos\n- ✅ **Documentação extensa** - Guias, exemplos e referência completa\n\n## 📦 Instalação\n\n```bash\nnpm install 3mf-pr-js\n```\n\n## 🎯 Uso Rápido\n\n### API de Alto Nível (Recomendado)\n\n```typescript\nimport { generate3MF } from '3mf-pr-js';\nimport { writeFile } from 'fs/promises';\n\nconst scene = {\n unit: 'millimeter',\n metadata: {\n Title: 'My 3D Model',\n Designer: 'Your Name'\n },\n basematerials: [\n { name: 'PLA Red', displaycolor: '#FF0000FF' }\n ],\n objects: [\n {\n type: 'mesh',\n name: 'Cube',\n vertices: [\n [0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0],\n [0, 0, 10], [10, 0, 10], [10, 10, 10], [0, 10, 10]\n ],\n triangles: [\n [0, 1, 2], [0, 2, 3],\n [4, 6, 5], [4, 7, 6],\n [0, 5, 1], [0, 4, 5],\n [1, 6, 2], [1, 5, 6],\n [2, 7, 3], [2, 6, 7],\n [3, 4, 0], [3, 7, 4]\n ],\n materialIndex: 0\n }\n ]\n};\n\n// Gerar 3MF com validação e Production extension\nconst buffer = await generate3MF(scene, {\n production: true,\n validate: true\n});\n\nawait writeFile('output.3mf', buffer);\n```\n\n### API Fluente (Controle Detalhado)\n\n```typescript\nimport { Model } from '3mf-pr-js';\n\nconst model = new Model();\n\n// Configuração\nmodel.setUnit('millimeter');\nmodel.enableProduction(true);\nmodel.addMetadata('Title', 'Complex Model');\n\n// Materiais\nconst red = model.addBaseMaterial('PLA Red', '#FF0000FF');\nconst blue = model.addBaseMaterial('PLA Blue', '#0000FFFF');\n\n// Objetos\nconst cube = model.addMesh(\n [[0,0,0], [10,0,0], [10,10,0], [0,10,0], [0,0,10], [10,0,10], [10,10,10], [0,10,10]],\n [[0,1,2], [0,2,3], [4,6,5], [4,7,6], [0,5,1], [0,4,5], [1,6,2], [1,5,6], [2,7,3], [2,6,7], [3,4,0], [3,7,4]],\n { name: 'Cube', material: red }\n);\n\n// Assembly\nconst assembly = model.addComponentObject('Assembly', [\n { objectid: cube, transform: [1,0,0, 0,1,0, 0,0,1, 0,0,0] },\n { objectid: cube, transform: [1,0,0, 0,1,0, 0,0,1, 15,0,0] }\n]);\n\n// Build item\nmodel.addBuildItem(assembly, [1,0,0, 0,1,0, 0,0,1, 50,50,0]);\n\n// Gerar\nconst buffer = await model.to3MF();\nawait model.writeToFile('output.3mf');\n```\n\n## 🛠️ Geração via API\n\nUse a API para gerar 3MFs programaticamente. Exemplos:\n\n```bash\nnpm run build\nnode examples/materials-api.mjs\n```\n\n## 📋 Recursos Avançados\n\n### Múltiplos Conjuntos de Materiais\n\n```typescript\nconst model = new Model();\n\n// Criar conjuntos separados\nmodel.createBaseMaterialsSet(1); // PLA\nmodel.createBaseMaterialsSet(2); // ABS\n\nconst pla_red = model.addBaseMaterial('PLA Red', '#FF0000FF', 1);\nconst abs_black = model.addBaseMaterial('ABS Black', '#000000FF', 2);\n\nmodel.addMesh(vertices, triangles, { material: pla_red });\nmodel.addMesh(vertices2, triangles2, { material: abs_black });\n```\n\n### Multifile (Production)\n\n```typescript\nmodel.enableProduction(true);\n\n// Criar part externo\nconst ext = model.addExternalMesh(\n '3D/parts/widget.model',\n 'Widget',\n vertices,\n triangles,\n { material: myMaterial }\n);\n\n// Referenciar no build\nmodel.addExternalBuildItem(ext.objectid, ext.path, transform);\n```\n\n### Validação de Geometria\n\n```typescript\nimport { validateWindingOrder, validateManifold } from '3mf-pr-js';\n\n// Verificar winding order\nconst windingResult = validateWindingOrder(vertices, triangles);\nif (!windingResult.ok) {\n console.warn('Winding warnings:', windingResult.warnings);\n}\n\n// Verificar manifold\nconst manifoldResult = validateManifold(vertices, triangles);\nif (!manifoldResult.ok) {\n console.error('Manifold errors:', manifoldResult.errors);\n}\n```\n\n### Thumbnails\n\n```typescript\nimport { readFile } from 'fs/promises';\n\n// PNG em /Thumbnails (padrão)\nconst thumb = await readFile('thumbnail.png');\nmodel.setThumbnail(thumb, 'png');\n\n// JPEG em /Metadata\nconst jpg = await readFile('thumbnail.jpg');\nmodel.setThumbnail(jpg, 'jpg', 'Metadata');\n\n// Thumbnail por objeto\nmodel.setObjectThumbnail(cube, thumb, 'png', 'Metadata');\n```\n\n### Otimização de Memória\n\n```typescript\nimport { Model, deduplicateVertices, estimateMemoryUsage } from '3mf-pr-js';\n\nconst model = new Model();\n\n// TypedArrays para eficiência máxima\nconst vertices = new Float32Array([/* ... */]);\nconst triangles = new Uint32Array([/* ... */]);\n\n// Adicionar com deduplicação automática\nmodel.addMeshOptimized(vertices, triangles, {\n name: 'Large Mesh',\n deduplicate: true, // Remove vértices duplicados\n reuseGeometry: true, // Reutiliza geometrias idênticas\n});\n\n// Estimar uso de memória\nconst usage = estimateMemoryUsage(vertices, triangles);\nconsole.log(`Memória: ${(usage.total / 1024 / 1024).toFixed(2)} MB`);\nconsole.log(`Economia potencial: ${usage.savings}`);\n\n// Ver estatísticas do pool\nconst stats = model.getGeometryPoolStats();\nconsole.log(`Geometrias únicas: ${stats.poolSize}`);\nconsole.log(`Economia: ~${((stats.totalRefs - stats.poolSize) / stats.totalRefs * 100).toFixed(0)}%`);\n```\n\n> 💡 **Veja o guia completo:** [MEMORY_OPTIMIZATION.md](./MEMORY_OPTIMIZATION.md)\n\n### Triangle Sets (Extensão)\n\n```typescript\n// Criar um conjunto de triângulos e adicionar referências\nconst idx = model.addTriangleSet(cube, 'Faces Superiores', 't:topFaces');\nmodel.addTriangleSetRefs(cube, idx, [0, 1, { startindex: 2, endindex: 5 }]);\n```\n\n### Partnumbers e MustPreserve\n\n```typescript\n// Partnumber em objeto e build item\nmodel.setObjectPartNumber(cube, 'PN-001');\nmodel.addBuildItem(cube, undefined, { partnumber: 'BI-001' });\n\n// Adicionar part customizado com MustPreserve\nmodel.addPreservePart('/Metadata/notes.txt', 'Informações importantes');\n```\n\n### Materials Extension (Color Groups)\n\n```typescript\n// Criar grupo de cores e adicionar cores\nconst groupId = model.createColorGroup();\nconst red = model.addColorToGroup('#FF0000FF', 'Red', groupId);\nconst green = model.addColorToGroup('#00FF00FF', 'Green', groupId);\n\n// Usar o grupo como default do objeto\nconst colored = model.addMesh(vertices, triangles, { name: 'Colored', material: red });\n\n// Override por triângulo usando pid/p1..p3\nmodel.setTriangleMaterials(colored, [\n { index: 0, pid: red.pid, p1: red.pindex, p2: red.pindex, p3: red.pindex },\n { index: 1, pid: green.pid, p1: green.pindex, p2: green.pindex, p3: green.pindex },\n]);\n```\n\n### Texturas (Texture2D)\n\n```typescript\nimport { readFile } from 'fs/promises';\n\n// Adicionar um recurso de textura PNG/JPEG\nconst png = await readFile('texture.png');\nconst texId = model.addTexture(png, 'png');\n// O recurso é emitido como `m:texture2d` e embalado em `3D/Textures/`\n```\n\n### Property Resources (Composite/Multi)\n\n```typescript\n// CompositeMaterials: mistura de entradas de um basematerials\nconst setId = model.createBaseMaterialsSet();\nmodel.addBaseMaterial('Red', '#FF0000FF', setId);\nmodel.addBaseMaterial('Blue', '#0000FFFF', setId);\nconst compId = model.createCompositeMaterials(setId);\nconst mix = model.addComposite(compId, [0.5, 0.5]); // soma=1.0\nmodel.addMesh(vertices, triangles, { material: { pid: compId, pindex: mix } });\n\n// MultiMaterials: combina recursos por índice (ex.: dois pids)\nconst setA = model.createBaseMaterialsSet();\nconst aMat = model.addBaseMaterial('A', '#FF0000FF', setA);\nconst setB = model.createBaseMaterialsSet();\nmodel.addBaseMaterial('B', '#0000FFFF', setB);\nconst mmId = model.createMultiMaterials([setA, setB]);\nconst combo = model.addMultiMaterial(mmId, [aMat.pindex, 0]);\nmodel.addMesh(vertices, triangles, { material: { pid: mmId, pindex: combo } });\n```\n\n## 📚 Documentação Completa\n\n### Guias Principais\n\n| Documento | Descrição | Público |\n|-----------|-----------|---------|\n| **[GETTING_STARTED.md](./GETTING_STARTED.md)** | Tutorial passo-a-passo para iniciantes | 🟢 Iniciante |\n| **[API.md](./API.md)** | Referência completa da API | 🔵 Intermediário/Referência |\n| **[CONCEPTS.md](./CONCEPTS.md)** | Conceitos fundamentais do 3MF | 🔵 Intermediário |\n| **[EXAMPLES.md](./EXAMPLES.md)** | Exemplos práticos de uso | 🟢 Todos |\n| **[MEMORY_OPTIMIZATION.md](./MEMORY_OPTIMIZATION.md)** | 🚀 Otimização de memória e performance | 🔵 Intermediário |\n| **[VALIDATION.md](./VALIDATION.md)** | Guia de validação | 🔵 Intermediário |\n| **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** | Solução de problemas comuns | 🟢 Todos |\n| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | Guia para contribuidores | 🟣 Avançado |\n| **[CHANGELOG.md](./CHANGELOG.md)** | Histórico de mudanças | 📋 Referência |\n\n### Documentação Técnica\n\nPara documentação técnica detalhada, consulte a pasta [`docs/`](./docs/):\n\n| Documento | Descrição |\n|-----------|-----------|\n| [**INDEX.md**](./docs/INDEX.md) | 📑 Índice navegável de toda documentação |\n| [020-especificacao-core.md](./docs/020-especificacao-core.md) | Core 3MF Specification |\n| [030-extensao-production.md](./docs/030-extensao-production.md) | Production Extension |\n| [080-esquema-entrada.md](./docs/080-esquema-entrada.md) | JSON Schema |\n| [110-exemplos-xml.md](./docs/110-exemplos-xml.md) | Exemplos XML |\n| [120-referencia-rapida.md](./docs/120-referencia-rapida.md) | Referência rápida |\n| [140-status-compatibilidade.md](./docs/140-status-compatibilidade.md) | Status de compatibilidade |\n\n> 💡 **Dica:** Comece com [GETTING_STARTED.md](./GETTING_STARTED.md) se você é novo na biblioteca!\n\n## 🧪 Testes\n\n```bash\nnpm test # Rodar todos os testes\nnpm run dev:test # Watch mode\n```\n\n**Cobertura**: 58 testes passando\n- Core 3MF (6 testes)\n- Recursos avançados (12 testes)\n- API generate3MF (9 testes)\n- Validação (11 testes)\n\n## 🎨 Exemplos\n\nVeja a pasta `examples/`:\n\n- `minimal.json` - Exemplo mínimo\n- `complex.json` - Assembly com múltiplos objetos e materiais\n- `api-usage.js` - Uso programático da API\n\n## 📖 API Reference\n\n### `generate3MF(scene, options)`\n\n```typescript\ninterface Generate3MFOptions {\n production?: boolean; // Habilitar Production extension\n validate?: boolean; // Validar entrada (default: true)\n strictValidation?: boolean; // Throw em erro de validação (default: true)\n}\n\nfunction generate3MF(scene: SceneJSON, options?: Generate3MFOptions): Promise\n```\n\n### Classe `Model`\n\n```typescript\nclass Model {\n // Configuração\n setUnit(unit: 'millimeter' | 'inch' | 'micron' | 'centimeter' | 'foot' | 'meter'): void\n setLanguage(lang: string): void\n enableProduction(enable?: boolean): void\n \n // Metadados\n addMetadata(name: string, value: string): void\n \n // Materiais\n createBaseMaterialsSet(id?: number): number\n addBaseMaterial(name: string, displaycolor: string, setId?: number): { pid: number; pindex: number }\n \n // Objetos\n addMesh(vertices: Vec3[], triangles: Triangle[], opts?: MeshOptions): number\n addComponentObject(name: string, components: ComponentRef[]): number\n setTriangleMaterials(objectid: number, assignments: TriangleMaterial[]): void\n \n // Build\n addBuildItem(objectid: number, transform?: Transform): void\n \n // Multifile\n addExternalMesh(path: string, name: string, vertices: Vec3[], triangles: Triangle[], opts?: MeshOptions): { path: string; objectid: number }\n addExternalBuildItem(objectid: number, path: string, transform?: Transform): void\n \n // Thumbnails\n setThumbnail(data: Uint8Array, ext?: 'png' | 'jpg', dir?: 'Thumbnails' | 'Metadata'): void\n \n // Geração\n to3MF(): Promise\n writeToFile(path: string): Promise\n}\n```\n\n### Tipos\n\n```typescript\ntype Vec3 = [number, number, number];\ntype Triangle = [number, number, number];\ntype Transform = [\n number, number, number, // m00 m01 m02\n number, number, number, // m10 m11 m12\n number, number, number, // m20 m21 m22\n number, number, number // m30 m31 m32 (translation)\n];\n```\n\n## 🎯 Compatibilidade\n\n✅ **Testado com:**\n- Bambu Studio\n- PrusaSlicer\n- lib3mf validator\n\n✅ **Especificações:**\n- 3MF Core Specification v1.3\n- Production Extension v1.0\n- OPC Package compliant\n \n### Matriz de Compatibilidade (Bambu Studio)\n- Basematerials/displaycolor: visual; slicing recalcula configurações.\n- `m:colorgroup`: visual por objeto/triângulo; não afeta slicing.\n- Texturas/UVs (`m:texture2d`/`m:texture2dgroup`): visual; lib3mf aceita `texture2d`; UVs são validados estruturalmente.\n- Property Resources (`m:compositematerials`, `m:multimaterials`): estrutural/visual; suporte varia por consumidor.\n- Thumbnails (pacote/objeto): apenas visual.\n- Triangle Sets (`t:`): organizacional; não afeta slicing.\n- Production multifile (`p:path`): assemblies preservados; slicer usa geometria consolidada.\n- PrintTicket: opcional; Bambu Studio não requer.\n\n## 🤝 Contribuindo\n\nContribuições são bem-vindas! Veja o roadmap em `docs/130-plano-implementacao.md`.\n\n## 📄 Licença\n\nMIT\n\n## 🔗 Links Úteis\n\n- [3MF Consortium](https://3mf.io/)\n- [Core Specification](https://github.com/3MFConsortium/spec_core)\n- [Production Extension](https://github.com/3MFConsortium/spec_production)\n- [lib3mf SDK](https://github.com/3MFConsortium/lib3mf)\n\n---\n\n**Made with ❤️ for the 3D printing community**\n","readmeFilename":"README.md","_rev":"1-6ba5521a76b1987d5bc5efb6ef533052"}