StlTo3mf Technical Overview

30-Second Quickstart

Option A: Instant Browser Studio (Zero Install)

No build tools or installation needed. Simply open the Web Studio directly in your web browser:

1. Click Launch Web Studio or navigate to the converter root.
2. Drag & drop any ASCII or binary .stl model into the drop zone.
3. Inspect the interactive 3D WebGL preview and click ⚡ Convert & Download 3MF.

Option B: High-Throughput Native CLI

Compile the optimized native Rust binary using Cargo:

# Clone repository and build optimized release binary
git clone https://github.com/madireis/stl-to-3mf.git
cd stl-to-3mf
cargo build --release --bin stl-to-3mf

# Convert single STL with auto-repair, shell splitting, and profile sanitization
./target/release/stl-to-3mf convert model.stl -o model.3mf --strip-slicer-config

# Batch convert an entire directory in parallel using Rayon
./target/release/stl-to-3mf convert ./models/ -o ./output_3mf/ --threads 0

Subcommand: convert

Converts single STL files or entire directories into compliant 3MF packages with full mesh repair and shell splitting.

stl-to-3mf convert <INPUT> [OPTIONS]

Subcommand: inspect

Analyzes an STL or 3MF model's topology, dimensions, watertightness, and scale sanity without modifying the file.

# Human-readable diagnostic output
stl-to-3mf inspect complex_bracket.stl

# Structured JSON output for CI/CD and pre-flight pipelines
stl-to-3mf inspect complex_bracket.stl --json

Example JSON diagnostics schema returned by --json:

{
  "format": "binary",
  "raw_triangles": 48200,
  "deduplicated_vertices": 24102,
  "degenerate_facets_pruned": 14,
  "boundary_holes_detected": 2,
  "shells_count": 3,
  "is_watertight": true,
  "bounding_box": {
    "min": [-45.0, -22.5, 0.0],
    "max": [45.0, 22.5, 35.8],
    "dimensions": [90.0, 45.0, 35.8]
  },
  "scale_sanity": {
    "status": "normal",
    "suggested_multiplier": 1.0
  }
}

Subcommand: sanitize

Cleans an existing .3mf package downloaded from the web, stripping unsafe printer configuration overrides while maintaining geometry, colors, and components.

stl-to-3mf sanitize untrusted_download.3mf -o safe_clean.3mf

Recipe 1: Multi-Color Shell Separation for Bambu Studio & OrcaSlicer

Ensure disconnected pieces (e.g. eyes, buttons, body parts) become independent objects ready for filament assignment:

stl-to-3mf convert character_multicolor.stl -o character.3mf \
  --merge-tolerance 1e-6 \
  --strip-slicer-config

Recipe 2: Aggressive Hole Healing for Defective 3D Scans

Increase boundary perimeter tolerance to patch larger scanning holes and force normal alignment:

stl-to-3mf convert raw_scan.stl -o healed_scan.3mf \
  --hole-max-edges 256 \
  --merge-tolerance 1e-5 \
  --verbose

Recipe 3: Parallel Batch Directory Processing (PowerShell)

Convert all STL files in a folder into individual 3MF packages in Windows PowerShell:

Get-ChildItem -Path .\stls\ -Filter *.stl | ForEach-Object {
    $outPath = Join-Path .\3mf_output\ ($_.BaseName + ".3mf")
    stl-to-3mf convert $_.FullName -o $outPath --strip-slicer-config
}

Recipe 4: CI/CD Mesh Validation Gate (Bash + jq)

Verify that all generated mechanical parts in your repository are strictly watertight before merging pull requests:

for f in cad_exports/*.stl; do
  IS_WATERTIGHT=$(stl-to-3mf inspect "$f" --json | jq -r '.is_watertight')
  if [ "$IS_WATERTIGHT" != "true" ]; then
    echo "❌ Validation Failure: $f is NOT watertight!"
    exit 1
  fi
done
echo "✅ All CAD meshes verified 100% watertight."

Starting the Local Server

The local HTTP service in web/server.js requires zero external npm dependencies—it relies purely on standard Node.js modules (http, fs, path, child_process):

# Run with default port 3000
node web/server.js

# Run with custom port
PORT=8080 node web/server.js

REST API Reference

POST /api/convert

Accepts a multipart form with an STL file and parameters, returning a freshly packaged .3mf binary archive.

Example curl API Request:

curl -X POST http://localhost:3000/api/convert \
  -F "file=@sample_gear.stl" \
  -F "split_shells=true" \
  -F "repair=true" \
  -F "strip_slicer_config=true" \
  -o sample_gear.3mf

The client-side engine consists of five coordinated ES6 modules located in web/public/assets/js/:

• stl-parser.js: Ingests binary STL buffers via DataView and ASCII STLs using regex tokenizers directly into continuous Float32Array position buffers.
• mesh-repair.js: Implements spatial hash grid vertex welding ($10^{-6}\text{ mm}$ cell size), degenerate facet elimination, boundary loop edge extraction, and Gauss Divergence signed volume checks.
• shell-separator.js: Implements Disjoint Set Union (DSU) to group triangles sharing undirected edges into distinct shells with compact 0-based vertex re-indexing.
• viewer3d.js: Three.js WebGL viewport featuring OrbitControls, independent multi-color shell rendering, glowing red boundary hole wireframe highlights, and offscreen 256×256 thumbnail capture.
• threemf-packager.js: Builds compliant OPC ZIP packages entirely in memory using fflate, generating [Content_Types].xml, _rels/.rels, and 3D/3dmodel.model.

1. Gauss-Ostrogradsky Divergence Theorem for Signed Volume

Theorem: Let $\Omega \subset \mathbb{R}^3$ be a compact, orientable 3-manifold with piecewise smooth boundary $\partial \Omega$. For any continuously differentiable vector field $\mathbf{F}: \Omega \to \mathbb{R}^3$:

Choose the linear position vector field $\mathbf{F}(\mathbf{x}) = \frac{1}{3}\mathbf{x} = \frac{1}{3}(x\hat{\mathbf{i}} + y\hat{\mathbf{j}} + z\hat{\mathbf{k}})$. The divergence is constantly 1:

Substituting into the volume integral:

For a closed surface discretized into planar triangular facets $f_i = (\mathbf{p}_0, \mathbf{p}_1, \mathbf{p}_2)$, evaluating the surface integral yields the exact summation:

Decision Criterion: If $V(\Omega) > 0$, the surface facets are consistently wound counter-clockwise when viewed from the outside (normals point outward). If $V(\Omega) < 0$, the shell is inverted; StlTo3mf swaps vertices $\mathbf{p}_1 \leftrightarrow \mathbf{p}_2$ on all faces.

2. Newell's Method for 3D Polygon Normal Estimation

Boundary loops $[v_0, v_1, \dots, v_{k-1}]$ extracted from 3D meshes are often non-planar. Simple cross products of two edges fail when edges are collinear or noisy. Newell's algorithm calculates the exact projected area integrals along all three cardinal planes:

where index $k \equiv 0$ (cyclic loop). The unit normal is obtained by $\hat{\mathbf{n}} = \mathbf{N} / \|\mathbf{N}\|$. StlTo3mf projects the loop into 2D by dropping the axis with $\max(|n_x|, |n_y|, |n_z|)$, preventing coordinate distortion before ear-clipping.

3. Ear-Clipping Triangulation with Barycentric Containment

A vertex $w_i$ in a projected 2D polygon $P$ forms a clippable "ear" if it is strictly convex ($\det > 0$) and no other polygon vertex $w_j$ lies within the triangle $\Delta(w_{i-1}, w_i, w_{i+1})$. Point containment is verified using barycentric coordinates $(\lambda_1, \lambda_2, \lambda_3)$:

model.3mf (Deflate ZIP Archive)
├── [Content_Types].xml         # Declares MIME content types
├── _rels/
│   └── .rels                   # Root relationships linking model & thumbnail
├── 3D/
│   ├── 3dmodel.model           # 3MF geometric model XML ( & )
│   └── _rels/
│       └── 3dmodel.model.rels  # Thumbnail metadata relationship
└── Metadata/
    └── thumbnail.png           # 256x256 RGBA preview thumbnail

Multi-Shell 3D/3dmodel.model Architecture

When multi-shell separation is enabled, each disjoint component is serialized as an independent <object> element with its own unique ID and coordinate buffer:

<?xml version="1.0" encoding="UTF-8"?>
<model unit="millimeter" xml:lang="en-US"
       xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02"
       xmlns:m="http://schemas.microsoft.com/3dmanufacturing/material/2015/02">
  <metadata name="Title">StlTo3mf Multi-Shell Export</metadata>
  <metadata name="Application">StlTo3mf (Omni3MF Engine)</metadata>

  <resources>
    <!-- Color Palette Definition -->
    <m:colorgroup id="1">
      <m:color color="#38BDF8FF" />
      <m:color color="#F97316FF" />
    </m:colorgroup>

    <!-- Object 1: Body Shell -->
    <object id="2" name="Shell_1" type="model" pid="1" pindex="0">
      <mesh>
        <vertices> ... </vertices>
        <triangles> ... </triangles>
      </mesh>
    </object>

    <!-- Object 2: Detail Shell -->
    <object id="3" name="Shell_2" type="model" pid="1" pindex="1">
      <mesh>
        <vertices> ... </vertices>
        <triangles> ... </triangles>
      </mesh>
    </object>
  </resources>

  <build>
    <item objectid="2" />
    <item objectid="3" />
  </build>
</model>

Bambu Studio & OrcaSlicer Workflow

1. Open Bambu Studio or OrcaSlicer.
2. Drag your converted .3mf file directly onto the build plate.
3. When prompted: "Load these objects as a single multi-part object?", select Yes.
4. Each separated shell appears in the left object list, allowing 1-click filament / AMS color assignment.

Why Programmatic Synthetic Testing?

To maintain a lightweight git history without checking multi-megabyte binary STL files into the repository, all test meshes are mathematically generated in Rust:

• Canonical Cubes: 12 triangles forming watertight 2-manifold closed boundaries.
• Deliberate Holes: Cubes with dropped faces verifying boundary edge cycle extraction and ear-clipping hole patches.
• Degenerate Facets: Collinear zero-area triangles and duplicate vertices verifying sub-micron spatial hash welding.
• Compound Shells: Multiple separated shapes testing DSU graph clustering and 0-based re-indexing.

Running Verification Gates

Before submitting any pull request, ensure all test gates pass cleanly:

# 1. Check code formatting
cargo fmt --all -- --check

# 2. Enforce zero compiler & clippy warnings
cargo clippy --workspace --all-targets -- -D warnings

# 3. Execute all 85 workspace synthetic and invariant tests
cargo test --workspace

# 4. Execute client-side web engine verification suite
node test/client_engine_test.js