occt-gltf-addon 0.1.0 → 0.1.2

package/README.md

@@ -2,22 +2,25 @@
 
 Node.js N-API 原生扩展：使用 OpenCascade (OCCT) 将 **STEP (.step/.stp)** 转换为 **glTF 2.0 (GLB)**。
 
-#### 安装（从 npm 安装会本地编译）
+#### 安装
 
-这个包默认会在 `npm install` 时执行本地编译（`cmake-js`）。
+- **Linux x64（Ubuntu 等）**：默认会安装预编译包 `occt-gltf-addon-linux-x64`（包含 OCCT runtime），一般 **不需要系统安装 OCCT**。
+- **macOS / 其他平台**：默认会在 `npm install` 时本地编译（`cmake-js`），需要 OCCT 开发文件（headers + libs）。
 
-你需要：
-- **CMake + C++ 编译器 + Python3**
-- **OCCT 安装**（共享库 + headers）
-
-通过环境变量指定 OCCT 安装前缀：
+本地编译时通过环境变量指定 OCCT 安装前缀：
 
 ```bash
 export OCCT_ROOT=/path/to/occt/prefix
 npm i occt-gltf-addon
 ```
 
-可选（启用 Draco 压缩需要开发包）：
+如需在 linux-x64 **强制源码编译**（不推荐，且需要你自己装 OCCT）：
+
+```bash
+OCCT_GLTF_ADDON_FORCE_BUILD=1 OCCT_ROOT=/path/to/occt/prefix npm i occt-gltf-addon
+```
+
+可选（仅在 **源码编译** 时用于启用 Draco 支持，需要开发包）：
 - `brew install draco` / `apt-get install libdraco-dev`
 
 如需跳过编译（不推荐，运行时会找不到 `.node`）：
@@ -55,6 +58,19 @@ await convertSTEPToGLTF({
 
 ---
 
+#### Smoke Test（安装后快速验证）
+
+```bash
+npm run smoke -- /abs/path/to/model.step /tmp/occt-gltf-out --draco --zup
+```
+
+参数：
+- `--draco`：启用 Draco 输出（可选）
+- `--zup`：导出 Z-up（用于 three.js Z-up 世界；可选）
+- `--quiet`：静默日志（可选）
+
+---
+
 #### 关键选项说明（简版）
 
 - **tessellation.linearDeflection / angularDeflection**：B-Rep 三角化精度

package/index.js

@@ -40,9 +40,10 @@ const msg = [
   '[occt-gltf-addon] Failed to load native addon (.node).',
   `Tried: ${candidates.map((p) => JSON.stringify(p)).join(', ')}`,
   '',
-  'If you installed from npm, ensure native build succeeded:',
-  '- CMake + C++ toolchain are installed',
-  "- OCCT is installed and OCCT_ROOT points to its install prefix (e.g. '/opt/homebrew', '/usr', '/usr/local', or your custom install)",
+  'If you installed from npm:',
+  '- On linux-x64: you should get the prebuilt optional dependency `occt-gltf-addon-linux-x64` (no system OCCT required).',
+  '  Ensure optional deps are enabled (do NOT use `--no-optional`).',
+  '- Otherwise / if building from source: ensure CMake + C++ toolchain are installed, and OCCT_ROOT points to your OCCT install prefix',
   '',
   "You can try: 'npm rebuild occt-gltf-addon' (with OCCT_ROOT exported).",
 ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "occt-gltf-addon",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "STEP (.step/.stp) to glTF (GLB) converter using OpenCascade (OCCT) via a Node.js N-API addon",
   "type": "commonjs",
   "main": "index.js",
@@ -46,7 +46,8 @@
     "CMakeLists.txt",
     "src/**",
     "scripts/**",
-    "example.js"
+    "example.js",
+    "smoke_test.js"
   ],
   "scripts": {
     "install": "node scripts/install.js",
@@ -54,6 +55,7 @@
     "clean": "rm -rf build",
     "rebuild": "npm run clean && npm run build",
     "example": "node example.js",
+    "smoke": "node smoke_test.js",
     "test": "node -e \"console.log('no tests')\"",
 
     "docker:build:linux-amd64": "bash docker/build-linux-amd64.sh",
@@ -61,7 +63,7 @@
     "docker:image:linux-amd64:nocache": "docker buildx build --no-cache --platform linux/amd64 -f docker/Dockerfile.linux-amd64 -t occt-addon-build:linux-amd64 ../.."
   },
   "optionalDependencies": {
-    "occt-gltf-addon-linux-x64": "0.1.0"
+    "occt-gltf-addon-linux-x64": "0.1.2"
   },
   "dependencies": {
     "cmake-js": "^7.3.1",

package/scripts/install.js

@@ -43,8 +43,19 @@ function main() {
       note(`Using prebuilt binary from ${prebuiltName}; skipping local build.`);
       return;
     } catch (e) {
-      // Prebuilt missing or not loadable (e.g. GLIBC mismatch). Fall back to local build.
-      note(`Prebuilt package ${prebuiltName} not usable; falling back to local build.`);
+      // Prebuilt missing or not loadable (e.g. GLIBC mismatch).
+      // On Linux, the default expectation is to use the prebuilt package (no system OCCT required).
+      // Only fall back to local build when the user explicitly opts in.
+      const canBuildFromSource =
+        process.env.OCCT_GLTF_ADDON_FORCE_BUILD === '1' || !!process.env.OCCT_ROOT;
+      if (!canBuildFromSource) {
+        note(`Prebuilt package ${prebuiltName} not usable, and OCCT_ROOT is not set.`);
+        note('This package is intended to work on Linux via the prebuilt optional dependency.');
+        note('Fix: ensure optional dependencies are installed (do NOT use --no-optional).');
+        note('Or: set OCCT_ROOT and re-install to build from source (or set OCCT_GLTF_ADDON_FORCE_BUILD=1).');
+        process.exit(1);
+      }
+      note(`Prebuilt package ${prebuiltName} not usable; attempting local build from source...`);
     }
   }
 
@@ -53,15 +64,24 @@ function main() {
     note("OCCT_ROOT is not set. If build fails, set OCCT_ROOT to your OCCT install prefix (e.g. '/opt/homebrew', '/usr', '/usr/local', or your custom install).");
   }
 
-  // Use the locally installed cmake-js (dependency).
-  const cmakeJsBin = path.join(pkgRoot, 'node_modules', '.bin', process.platform === 'win32' ? 'cmake-js.cmd' : 'cmake-js');
-  if (!fs.existsSync(cmakeJsBin)) {
-    note(`cmake-js not found at ${cmakeJsBin}. Try: 'npm install' again.`);
+  note('Building native addon with cmake-js...');
+
+  // Locate cmake-js CLI in a way that works with npm hoisting.
+  let cmakeJsCli = null;
+  try {
+    // eslint-disable-next-line global-require
+    cmakeJsCli = require.resolve('cmake-js/bin/cmake-js');
+  } catch (e) {
+    cmakeJsCli = null;
+  }
+
+  if (!cmakeJsCli || !fs.existsSync(cmakeJsCli)) {
+    note('cmake-js is not available (dependency missing).');
+    note("Try: 'npm install' again.");
     process.exit(1);
   }
 
-  note('Building native addon with cmake-js...');
-  run(cmakeJsBin, ['compile', '-O', 'build'], { cwd: pkgRoot, env: process.env });
+  run(process.execPath, [cmakeJsCli, 'compile', '-O', 'build'], { cwd: pkgRoot, env: process.env });
 }
 
 try {

package/smoke_test.js

@@ -0,0 +1,152 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function usage() {
+  console.error('Usage: node smoke_test.js <input.step> [outputDir] [--draco] [--zup] [--quiet]');
+  console.error('');
+  console.error('Notes:');
+  console.error('- Requires OCCT runtime libraries to be available at runtime (LD_LIBRARY_PATH / rpath / system install).');
+  console.error('- If you use three.js Z-up world (THREE.Object3D.DEFAULT_UP.set(0,0,1)), pass --zup.');
+}
+
+function readU32LE(buf, off) {
+  return buf.readUInt32LE(off);
+}
+
+function parseGlbHeaderAndJson(glbPath) {
+  const fd = fs.openSync(glbPath, 'r');
+  try {
+    const header = Buffer.alloc(12);
+    fs.readSync(fd, header, 0, 12, 0);
+    const magic = header.toString('ascii', 0, 4);
+    const version = readU32LE(header, 4);
+
+    if (magic !== 'glTF' || version !== 2) {
+      throw new Error(`Not a glTF 2.0 GLB: magic=${magic}, version=${version}`);
+    }
+
+    const chunk0 = Buffer.alloc(8);
+    fs.readSync(fd, chunk0, 0, 8, 12);
+    const jsonLen = readU32LE(chunk0, 0);
+    const jsonType = readU32LE(chunk0, 4);
+    if (jsonType !== 0x4e4f534a) {
+      throw new Error(`Invalid JSON chunk type: 0x${jsonType.toString(16)}`);
+    }
+
+    const jsonBuf = Buffer.alloc(jsonLen);
+    fs.readSync(fd, jsonBuf, 0, jsonLen, 20);
+    const jsonStr = jsonBuf.toString('utf8').replace(/\s+$/g, '');
+    const gltf = JSON.parse(jsonStr);
+    return { gltf };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const flags = new Set(argv.filter((a) => a.startsWith('--')));
+  const positional = argv.filter((a) => !a.startsWith('--'));
+
+  const inputPath = positional[0];
+  if (!inputPath) {
+    usage();
+    process.exit(1);
+  }
+
+  const outputDir = positional[1] || fs.mkdtempSync(path.join(os.tmpdir(), 'occt-gltf-addon-'));
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const enableDraco = flags.has('--draco');
+  const zUp = flags.has('--zup');
+  const quiet = flags.has('--quiet');
+
+  const baseName = path.parse(inputPath).name || 'out';
+  const outMin = path.join(outputDir, `${baseName}.min.glb`);
+  const outNormal = path.join(outputDir, `${baseName}.glb`);
+
+  // Require the package under test.
+  // In a consumer project, this should be: require('occt-gltf-addon')
+  // Here we use '.' so it works when running inside the package directory too.
+  // eslint-disable-next-line global-require, import/no-dynamic-require
+  const { convertSTEPToGLTF } = require('.');
+
+  const outputOpts = {
+    unit: 'm',
+    bakeTransforms: true,
+    center: zUp ? 'xy' : 'xz',
+    zUp,
+    draco: enableDraco
+      ? { enabled: true, compressionLevel: 7, quantizationBitsPosition: 14, quantizationBitsNormal: 10 }
+      : { enabled: false },
+  };
+
+  const variants = [
+    {
+      outputPath: outMin,
+      tessellation: { linearDeflection: 5, angularDeflection: Math.PI / 3 },
+      filter: { minBBoxDiagonal: 60 },
+      output: outputOpts,
+    },
+    {
+      outputPath: outNormal,
+      tessellation: { linearDeflection: 0.2, angularDeflection: 0.6, smoothNormals: true, normalCreaseAngle: Math.PI / 3 },
+      output: outputOpts,
+    },
+  ];
+
+  console.log('[smoke] input:', inputPath);
+  console.log('[smoke] outputDir:', outputDir);
+  console.log('[smoke] draco:', enableDraco);
+  console.log('[smoke] zUp:', zUp);
+
+  await convertSTEPToGLTF({
+    inputPath,
+    logLevel: quiet ? 'quiet' : 'info',
+    variants,
+  });
+
+  for (const p of [outMin, outNormal]) {
+    if (!fs.existsSync(p)) {
+      throw new Error(`Missing output file: ${p}`);
+    }
+    const st = fs.statSync(p);
+    if (st.size < 32) {
+      throw new Error(`Output file too small: ${p} (${st.size} bytes)`);
+    }
+
+    const { gltf } = parseGlbHeaderAndJson(p);
+    const nodes = Array.isArray(gltf.nodes) ? gltf.nodes.length : 0;
+    const meshes = Array.isArray(gltf.meshes) ? gltf.meshes.length : 0;
+    const nodesWithMatrix = Array.isArray(gltf.nodes)
+      ? gltf.nodes.reduce((n, x) => n + (x && Object.prototype.hasOwnProperty.call(x, 'matrix') ? 1 : 0), 0)
+      : 0;
+
+    if (nodes === 0 || meshes === 0) {
+      throw new Error(`Invalid glTF content in ${p}: nodes=${nodes}, meshes=${meshes}`);
+    }
+    if (nodesWithMatrix !== 0) {
+      throw new Error(`Expected baked transforms (no node.matrix). Got nodesWithMatrix=${nodesWithMatrix} in ${p}`);
+    }
+
+    if (enableDraco) {
+      const used = gltf.extensionsUsed || [];
+      if (!used.includes('KHR_draco_mesh_compression')) {
+        throw new Error(`Expected Draco extensionUsed in ${p}`);
+      }
+    }
+
+    console.log('[smoke] OK:', p, `(${st.size} bytes)`);
+  }
+
+  console.log('[smoke] PASS');
+}
+
+main().catch((e) => {
+  console.error('[smoke] FAIL');
+  console.error(e && (e.stack || e.message || e));
+  process.exit(1);
+});
+