PhoenixBlack-Nest – True shape nesting library in Python for CNC/laser cutting

GPU true-shape nesting for industrial cutting. Reads DXF/DWG/SVG/PDF and images, extracts the real contour of every part (holes included), packs them onto fixed sheets or a continuous roll without overlap, and exports DXF 1:1 mm plus print-ready imposition PDFs.

A real production run: 14 references, 263 copies, one 5.12 m roll at 64.1 %.

Manual CAD nesting wastes material: parts are placed by bounding box, holes and islands are ignored, and the gaps between complex shapes are thrown away. Worse, verifying that two parts never touch is an expensive geometric test that a sequential loop cannot run hundreds of thousands of times per second.

True-shape intake — DXF (LINE/ARC/SPLINE/LWPOLYLINE with topological stitching), DWG (via ODA File Converter if installed), SVG (transforms, curves, use), vector PDF, and rasters (PNG/JPG/TIFF/WEBP/BMP) with silhouette detection.

Contour hierarchy — outer boundary, holes and islands are kept apart, and every part is normalized to real millimeters.

GPU evaluation — a WebGL2 engine rasterizes the sheet and all parts into a 2048×1024 ping-pong buffer, evaluates up to 8 parts per pass with 96 samples per part, and prunes doomed pixels inside the shader.

Slide to contact — each candidate is slid until it touches the geometry already placed, honoring the exact spacing.

Genetic search — selection, 1° rotation steps, and a fine window around the best candidates.

Sheets or roll — multi-sheet layouts, or a continuous roll with an incrementally extended occupancy grid.

Export — DXF with closed LWPOLYLINE on the CutContour layer ($INSUNITS=4) and an imposition PDF with cut marks and bleed.

Measured performance

Metric Value

Roll utilization (real batch, 144 parts) 72.2 %

Fixed-sheet utilization (audit set, 180 parts, 24 complex shapes) 54.3 %

Material overlap 0.000000 mm²

Minimum clearance 3.0000 mm (configured spacing)

Batch evaluation cost 3.78 ms

Search rate 4.23 s/gen (sheets) · 4.96 s/gen (roll)

Measured on Windows 11 with an Intel Arc GPU; results depend on the machine and the shape mix.

Windows x64

Node.js 18+ and npm (for Electron)

Python 3.13 with shapely ezdxf reportlab pillow numpy opencv-python-headless pymupdf pypdf

npm install python -m pip install shapely ezdxf reportlab pillow numpy opencv-python-headless pymupdf pypdf

Usage

run.bat

or

npm start

Import — drag or pick DXF/DWG/SVG/PDF/images. Each file is converted to contours in millimeters, with detected vertices and holes.

Configure — sheet size or roll mode, spacing, bleed, copies per part and rotation step.

Nest — the engine runs in a hidden GPU worker and reports every generation. Stop it at any time.

Export — DXF 1:1 mm (CutContour) and imposition PDF.

Environment variables:

node_modules\electron\dist\electron.exe tests\test_precision_1deg.js node_modules\electron\dist\electron.exe tests\test_real_stress.js node_modules\electron\dist\electron.exe tests\test_roll.js

Reproducible benchmark (same seed, same instance, per-run GPU counters):

set NEST_SAMPLES=D:\path\to\dxf_batch
set PBN_SEED=12345 set DUR=25000 node_modules\electron\dist\electron.exe tests\bench_engine.js

The engine accepts seed (deterministic ordering and angle exploration), so two runs with the same seed and inputs produce the same layout. bench_engine.js prints per-run generation throughput, utilisation and GPU batch/readback timings.

main.js Electron main process (windows, IPC, Python) worker/gpu_worker.html hidden GPU worker (WebGL2) worker/engine_bridge.js worker IPC bridge engine/universal_gpu_engine.js rasterization, evaluation, part mining engine/core_nesting_engine.js GA, sheets, roll, compaction, occupancy engine/local_cad_converter.py DXF/DWG/SVG/PDF/raster intake engine/pdf_imposition_exporter.py DXF 1:1 + imposition PDF ui/ decoupled interface

License and third parties

This project is distributed under the GNU Affero General Public License v3.0. If you distribute the program (or a service built on it), you must also offer the source under the same license.

If you need a closed-source distribution, replace PyMuPDF with a permissive alternative or obtain a commercial license from Artifex.