@iyulab/u-nesting 0.3.0

package/README.md

@@ -0,0 +1,192 @@
+# @iyulab/u-nesting
+
+**2D/3D Spatial Optimization Engine** — High-performance nesting and bin packing via WebAssembly.
+
+[![npm](https://img.shields.io/npm/v/@iyulab/u-nesting.svg)](https://www.npmjs.com/package/@iyulab/u-nesting)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/iyulab/U-Nesting/blob/main/LICENSE-MIT)
+
+## Installation
+
+```bash
+npm install @iyulab/u-nesting
+```
+
+## Functions
+
+| Function | Description |
+|----------|-------------|
+| `solve_2d(json: string): string` | Solve a 2D nesting problem |
+| `solve_3d(json: string): string` | Solve a 3D bin packing problem |
+| `optimize_cutting_path(json: string): string` | Optimize cutting path for placed parts |
+| `version(): string` | Get API version |
+| `available_strategies(): string` | List available strategies |
+
+All functions use **JSON string I/O**.
+
+## Usage
+
+### 2D Nesting
+
+```javascript
+import init, { solve_2d } from '@iyulab/u-nesting';
+
+await init();
+
+const result = JSON.parse(solve_2d(JSON.stringify({
+  geometries: [
+    {
+      id: "part-A",
+      polygon: [[0,0], [100,0], [100,50], [0,50]],
+      quantity: 3,
+      allow_flip: false,
+      rotations: [0, 90, 180, 270]
+    },
+    {
+      id: "part-B",
+      polygon: [[0,0], [60,0], [60,80], [0,80]],
+      quantity: 2
+    }
+  ],
+  boundary: { width: 500, height: 300 },
+  config: {
+    spacing: 2.0,
+    strategy: "ga",
+    population_size: 50,
+    max_generations: 100,
+    time_limit_ms: 5000
+  }
+})));
+
+console.log(result);
+// { success: true, placements: [...], utilization: 0.85, boundaries_used: 1, ... }
+```
+
+### 3D Bin Packing
+
+```javascript
+import init, { solve_3d } from '@iyulab/u-nesting';
+
+await init();
+
+const result = JSON.parse(solve_3d(JSON.stringify({
+  geometries: [
+    { id: "box-1", dimensions: [10, 20, 15], quantity: 5 },
+    { id: "box-2", dimensions: [8, 12, 10], quantity: 3, mass: 2.5 }
+  ],
+  boundary: {
+    dimensions: [100, 100, 100],
+    max_mass: 50.0,
+    gravity: true,
+    stability: true
+  },
+  config: {
+    strategy: "ga",
+    time_limit_ms: 3000
+  }
+})));
+```
+
+### Cutting Path Optimization
+
+```javascript
+import init, { solve_2d, optimize_cutting_path } from '@iyulab/u-nesting';
+
+await init();
+
+// First solve the nesting problem
+const solveResult = JSON.parse(solve_2d(JSON.stringify({ /* ... */ })));
+
+// Then optimize cutting path
+const cutting = JSON.parse(optimize_cutting_path(JSON.stringify({
+  geometries: [/* same geometries */],
+  solve_result: solveResult,
+  cutting_config: {
+    kerf_width: 0.5,
+    cut_speed: 100.0,
+    rapid_speed: 500.0,
+    exterior_direction: "cw",
+    interior_direction: "ccw"
+  }
+})));
+```
+
+## Input Schemas
+
+### `solve_2d` Request
+
+```typescript
+interface Request2D {
+  geometries: {
+    id: string;
+    polygon: [number, number][];       // Vertices (CCW)
+    quantity?: number;                  // Default: 1
+    allow_flip?: boolean;              // Default: false
+    rotations?: number[];              // Allowed rotation angles in degrees
+    holes?: [number, number][][];      // Interior holes
+  }[];
+  boundary: {
+    width?: number;                    // Rectangle boundary
+    height?: number;
+    polygon?: [number, number][];      // Or custom polygon boundary
+  };
+  config?: {
+    spacing?: number;                  // Part spacing (default: 0)
+    margin?: number;                   // Boundary margin (default: 0)
+    strategy?: string;                 // See available strategies
+    population_size?: number;          // GA/BRKGA population (default: 50)
+    max_generations?: number;          // GA/BRKGA generations (default: 100)
+    crossover_rate?: number;           // Crossover rate (default: 0.8)
+    mutation_rate?: number;            // Mutation rate (default: 0.1)
+    time_limit_ms?: number;            // Time limit in ms
+    target_utilization?: number;       // Stop early if reached
+  };
+}
+```
+
+### Available 2D Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `blf` | Bottom-Left Fill (fast, deterministic) |
+| `nfp` | NFP-Guided placement |
+| `ga` | Genetic Algorithm |
+| `brkga` | Biased Random-Key GA |
+| `sa` | Simulated Annealing |
+| `gdrr` | Guided Destroy-Repair-Refine |
+| `alns` | Adaptive Large Neighborhood Search |
+
+### Available 3D Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `blf` | Bottom-Left Fill |
+| `ep` | Extreme Point |
+| `ga` | Genetic Algorithm |
+| `brkga` | Biased Random-Key GA |
+| `sa` | Simulated Annealing |
+
+## Response Schema
+
+```typescript
+interface SolveResponse {
+  version: string;
+  success: boolean;
+  error?: string;
+  placements: {
+    geometry_id: string;
+    instance: number;
+    position: { x: number; y: number; z?: number };
+    rotation: { angle?: number; rx?: number; ry?: number; rz?: number };
+    boundary_index: number;
+  }[];
+  boundaries_used: number;
+  utilization: number;
+  unplaced: string[];
+  computation_time_ms: number;
+}
+```
+
+## Related
+
+- [u-geometry](https://www.npmjs.com/package/@iyulab/u-geometry) — Computational geometry primitives
+- [u-metaheur](https://crates.io/crates/u-metaheur) — Metaheuristic optimization framework

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@iyulab/u-nesting",
+  "type": "module",
+  "collaborators": [
+    "iyulab"
+  ],
+  "description": "WebAssembly bindings for U-Nesting spatial optimization engine",
+  "version": "0.3.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iyulab/U-Nesting"
+  },
+  "files": [
+    "u_nesting_wasm_bg.wasm",
+    "u_nesting_wasm.js",
+    "u_nesting_wasm_bg.js",
+    "u_nesting_wasm.d.ts"
+  ],
+  "main": "u_nesting_wasm.js",
+  "types": "u_nesting_wasm.d.ts",
+  "sideEffects": [
+    "./u_nesting_wasm.js",
+    "./snippets/*"
+  ],
+  "keywords": [
+    "nesting",
+    "bin-packing",
+    "wasm",
+    "webassembly"
+  ]
+}

package/u_nesting_wasm.d.ts

@@ -0,0 +1,39 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Returns a JSON array of available strategy names for WASM builds.
+ *
+ * MILP and HybridExact are not available in WASM (requires native HiGHS solver).
+ */
+export function available_strategies(): string;
+
+/**
+ * Optimizes cutting path for placed 2D parts.
+ *
+ * Input must include geometries, a previous solve result, and optional cutting config.
+ * Returns a JSON string with the cutting path result.
+ * On error, returns `{ "success": false, "error": "..." }`.
+ */
+export function optimize_cutting_path(request_json: string): string;
+
+/**
+ * Solves a 2D nesting problem from a JSON request string.
+ *
+ * Returns a JSON string with the solve result.
+ * On error, returns `{ "success": false, "error": "..." }`.
+ */
+export function solve_2d(request_json: string): string;
+
+/**
+ * Solves a 3D bin packing problem from a JSON request string.
+ *
+ * Returns a JSON string with the solve result.
+ * On error, returns `{ "success": false, "error": "..." }`.
+ */
+export function solve_3d(request_json: string): string;
+
+/**
+ * Returns the API version string.
+ */
+export function version(): string;

package/u_nesting_wasm.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./u_nesting_wasm.d.ts" */
+
+import * as wasm from "./u_nesting_wasm_bg.wasm";
+import { __wbg_set_wasm } from "./u_nesting_wasm_bg.js";
+__wbg_set_wasm(wasm);
+
+export {
+    available_strategies, optimize_cutting_path, solve_2d, solve_3d, version
+} from "./u_nesting_wasm_bg.js";

package/u_nesting_wasm_bg.js

@@ -0,0 +1,264 @@
+/**
+ * Returns a JSON array of available strategy names for WASM builds.
+ *
+ * MILP and HybridExact are not available in WASM (requires native HiGHS solver).
+ * @returns {string}
+ */
+export function available_strategies() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.available_strategies(retptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred1_0 = r0;
+        deferred1_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred1_0, deferred1_1, 1);
+    }
+}
+
+/**
+ * Optimizes cutting path for placed 2D parts.
+ *
+ * Input must include geometries, a previous solve result, and optional cutting config.
+ * Returns a JSON string with the cutting path result.
+ * On error, returns `{ "success": false, "error": "..." }`.
+ * @param {string} request_json
+ * @returns {string}
+ */
+export function optimize_cutting_path(request_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(request_json, wasm.__wbindgen_export3, wasm.__wbindgen_export4);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.optimize_cutting_path(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred2_0 = r0;
+        deferred2_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Solves a 2D nesting problem from a JSON request string.
+ *
+ * Returns a JSON string with the solve result.
+ * On error, returns `{ "success": false, "error": "..." }`.
+ * @param {string} request_json
+ * @returns {string}
+ */
+export function solve_2d(request_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(request_json, wasm.__wbindgen_export3, wasm.__wbindgen_export4);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.solve_2d(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred2_0 = r0;
+        deferred2_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Solves a 3D bin packing problem from a JSON request string.
+ *
+ * Returns a JSON string with the solve result.
+ * On error, returns `{ "success": false, "error": "..." }`.
+ * @param {string} request_json
+ * @returns {string}
+ */
+export function solve_3d(request_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(request_json, wasm.__wbindgen_export3, wasm.__wbindgen_export4);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.solve_3d(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred2_0 = r0;
+        deferred2_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Returns the API version string.
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.version(retptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred1_0 = r0;
+        deferred1_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred1_0, deferred1_1, 1);
+    }
+}
+export function __wbg_getRandomValues_3f44b700395062e5() { return handleError(function (arg0, arg1) {
+    globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+}, arguments); }
+export function __wbindgen_object_drop_ref(arg0) {
+    takeObject(arg0);
+}
+function addHeapObject(obj) {
+    if (heap_next === heap.length) heap.push(heap.length + 1);
+    const idx = heap_next;
+    heap_next = heap[idx];
+
+    heap[idx] = obj;
+    return idx;
+}
+
+function dropObject(idx) {
+    if (idx < 1028) return;
+    heap[idx] = heap_next;
+    heap_next = idx;
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) { return heap[idx]; }
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        wasm.__wbindgen_export(addHeapObject(e));
+    }
+}
+
+let heap = new Array(1024).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeObject(idx) {
+    const ret = getObject(idx);
+    dropObject(idx);
+    return ret;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+
+let wasm;
+export function __wbg_set_wasm(val) {
+    wasm = val;
+}