Documentation

Quick Start

Audit a single file (geometry only)

admeshio audit model.stl

Audit with printer profile

admeshio audit model.stl --recipe bambu_x1c_pla_standard

# full GRI-G + GRI-R + GRI-I against the recipe's printer/material envelope

Audit + HTML report

admeshio audit model.stl --format html --recipe elegoo_saturn3_std_resin_standard

Verify a sliced G-code (FDM)

admeshio verify print.gcode --recipe bambu_x1c_pla_standard

Verify a sliced resin file (CTB / cbddlp / pwmx / goo)

admeshio verify model.ctb --recipe elegoo_saturn3_std_resin_standard

# Phase 1: header + exposure / bottom-layer / Z-monotonic sanity

# Phase 2: floating islands, 3D-confirmed vacuum traps, peel spikes

# Profile compare: printer mismatch + lift-cycle divergence

Repair a broken mesh

admeshio repair input.stl -o output.stl

# Closes cracks, removes overlaps, leaves the design intact when it can

Folder batch (auto-parallel)

admeshio audit ./incoming --recursive --workers 8 \

--recipe bambu_x1c_pla_standard --summary report.html

# JSON + HTML reports written next to each source file

Or use the web app (no install)

Open /app
Drop your STL / OBJ / 3MF / GLB / PLY file
Quick Check runs instantly on your computer — file never uploaded

Example Output

Every audit and verify call returns the stable admeshio-report/v1 envelope. One parser, every verb. Fields below reflect the current current schema (Apr 2026).

All checks pass — mesh + user G-code

Full Audit (mesh + G-code). Every stage executed, no flags.

{
  "schema": "admeshio-report/v1",
  "version": "1.0.0",
  "op": "audit",
  "input": {
    "path": "part.stl",
    "hash": "fnv1a:ab63440108b35399",
    "bytes": 7084,
    "format": "stl"
  },
  "profile": "bambu_x1c_pla_standard",
  "success": true,
  "audited_at": "2026-04-19T15:05:11Z",
  "verdict": {
    "gri_overall": 87,
    "gri_geometry": 92,
    "gri_readiness": 90,
    "gri_inspection": 87,
    "bottleneck": "none"
  },
  "stages": [
    {"name": "diagnose",       "status": "executed", "elapsed_ms": 12},
    {"name": "audit_geometry", "status": "executed", "elapsed_ms": 34},
    {"name": "slice",          "status": "skipped",  "elapsed_ms": 0,
                               "skip_reason": "external G-code provided"},
    {"name": "verify_output",  "status": "executed", "elapsed_ms": 11}
  ],
  "billing": {"credits_charged": 3, "tier": "full_audit_external"},
  "flags": [],
  "errors": [],
  "timings": {"total_ms": 57}
}

Mesh fails geometry — audit stops early

Geometry check finds defects serious enough that slicing the mesh would be misleading — audit short-circuits and skips the remaining slice + verify stages.

{
  "schema": "admeshio-report/v1",
  "version": "1.0.0",
  "op": "audit",
  "input": {"path": "broken.stl", "hash": "fnv1a:fe9012...", "bytes": 6684, "format": "stl"},
  "profile": "bambu_x1c_pla_standard",
  "success": false,
  "audited_at": "2026-04-19T15:08:42Z",
  "verdict": {
    "gri_overall": 32,
    "gri_geometry": 32,
    "gri_readiness": null,
    "gri_inspection": null,
    "bottleneck": "geometry"
  },
  "stages": [
    {"name": "diagnose",       "status": "executed"},
    {"name": "audit_geometry", "status": "executed"},
    {"name": "slice",          "status": "skipped",
                               "skip_reason": "geometry below abort threshold"},
    {"name": "verify_output",  "status": "skipped"}
  ],
  "billing": {"credits_charged": 1, "tier": "deep_g", "refunded": 3},
  "flags": [
    {"code": "SELF_INTERSECTION", "severity": 0.8,
     "message": "242 overlapping face pairs"},
    {"code": "OPEN_BOUNDARY",     "severity": 0.4,
     "message": "10 open edge loops (4 cracks, 6 intentional)"}
  ],
  "errors": [],
  "timings": {"total_ms": 18}
}

CLI exit codes

0	The audit ran and produced findings (any number of warnings or fails)
1	The audit could not run (file not found, parse error, unsupported format, empty mesh)

AdMeshio reports findings — you decide the policy. Drop admeshio audit into CI and inspect the JSON output: branch on individual flags[].code entries (e.g. fail the build only on SELF_INTERSECTION) or on the verdict.gri_overall threshold of your choice.

Command reference

Twelve commands cover the workflow: check a mesh, verify a G-code, repair what's broken, simplify a heavy file, auto-orient for printing, boolean two meshes together. Every command emits the same JSON shape on stdout so you can drop any of them into a script.

Check & verify (read-only)

audit <mesh> --recipe X	Full audit against a printer + material recipe. Reports Topology / Readiness / Inspection scores.
audit <mesh> --recipe geometry_only	Mesh-only check, no printer needed. Fast hygiene pass.
audit <mesh> --repair	Repair the mesh inline before checking it.
verify <gcode> --recipe X	Check the G-code your slicer produced — temperatures, speeds, layer timing, collision.
diagnose <mesh>	Counts of common defects: cracks, overlaps, flipped faces, intentional openings.
thickness <mesh> --min-thickness N	Wall-thickness map. Filters out intentional thin features (blades, wires, membranes).
diff <a.stl> <b.stl>	How far apart two meshes are: max + mean deviation, bounding box, volume.
units <mesh>	Detect whether the mesh is in millimetres or inches.

Repair & modify

repair <mesh> -o <out>	Close cracks and overlaps. Designed never to make the input measurably worse — if a step would, it rolls back.
decimate <mesh> -o <out> --ratio R	Reduce triangle count while preserving the look. Has a built-in safety gate that rejects collapses creating new defects.
orient <mesh> -o <out>	Auto-orient for minimum support (FDM) or bed adhesion (SLA/SLS). Samples 100 candidate rotations and picks the lowest-score pose. Profile-aware via `--printer-profile`.
boolean <union\|subtract\|intersect> -i a.stl b.stl -o <out>	Exact mesh boolean (Manifold). Multi-operand cases fold left-to-right. Inputs must be watertight manifolds — run `repair` first if they aren't.
pipeline <mesh> -o <out> --recipe X	Run several repair / cleanup steps in order via a recipe file. Useful for shop workflows.

Slice (uses your slicer)

fdm-slice <mesh> --recipe X

Calls PrusaSlicer / OrcaSlicer / Bambu Studio under the hood, captures the G-code, and runs verify on it.

Help for a single verb: admeshio <verb> --help. List the built-in recipes: admeshio --list-recipes. You can also pass your own recipe file: --recipe ./my-shop.json.

Hollowing and arranging are not commands here — your slicer does both better. For SLA, turn on hollowing in the slicer profile; for FDM, use 0% infill. To arrange multiple parts on the plate, use the slicer's arrange UI.

Repair

Repair is built so the output is never measurably worse than the input — every step has a safety net that rolls back if it damages the mesh.

What repair guarantees

Strict mode: pass strict_quality:1 in your recipe and any step that breaks topology or makes overlaps worse will roll itself back.
Each step prints a one-line note when something out of the ordinary happens (a region was reverted, the input had supports we left untouched, the output triangle count grew a lot). Read the stderr — nothing is silent.
Different mesh sources need different settings. AI-generated meshes, hand-modelled CAD, scanned figurines, and architectural sets each have their own sweet-spot recipe — see the use cases page.

Profiles, folder batch & automation

Printer profiles

Every audit is evaluated against a specific printer + material profile (a "recipe"). The catalog covers the printers and materials shipped by OrcaSlicer, PrusaSlicer, and Bambu Studio — synced daily so a freshly-released vendor profile shows up within a day. Seven hand-tuned reference recipes cover the common cases out of the box (Bambu X1C / PLA, Elegoo Saturn 3 / resin, generic FDM presets, geometry-only). Drop in your own JSON file to encode shop-specific thresholds. A folder-wide policy file (.admeshiorc.yml) is on the roadmap.

# List reference recipes (canonical profiles also available via --list-canonical-printers)

admeshio --list-recipes

# Built-in recipe by name

admeshio audit model.stl --recipe elegoo_saturn3_std_resin_standard

# Custom recipe JSON file (shop-specific thresholds)

admeshio audit model.stl --recipe ./my_shop.json

# No printer yet? Geometry-only audit still runs.

admeshio audit model.stl --recipe geometry_only

Folder batch

Both audit and verify accept a directory and auto-parallelise. Each file gets its own JSON + HTML report written next to the source — one folder in, one folder out. Failed files (malformed, unsupported format) are skipped and don't count toward your plan's monthly usage. Auto-sort into ready/ / review/ / rejected/ buckets is on the roadmap.

# Audit every mesh in ./orders

admeshio audit ./orders --recursive --workers 8 \

--recipe bambu_x1c_pla_standard

# Batch verify G-code files (post-slice inspection)

admeshio verify ./gcodes --recursive --workers 4 \

--recipe bambu_x1c_pla_standard

# Mesh + matching G-code pairs in one folder

admeshio audit ./orders --recursive --auto-pair

Batch flags

--recursive	Scan subfolders
--workers N	Parallel worker count (default: cores/2)
--limit N	Max files to process (useful for dry runs)
--format html	Also write a self-contained HTML report next to each file
--auto-pair	When the folder has a mesh + matching G-code (same stem), audit them together

CI / build pipeline integration

Drop the CLI straight into a build step. Exit code is derived from the audit result, so the standard "fail the job on non-zero" wiring already works — no separate flag needed.

# GitHub Actions — fail the job on any unprintable mesh

- name: Audit 3D models

run: admeshio audit ./models --recursive --format html

- uses: actions/upload-artifact@v4

if: always()

with: { name: audit-reports, path: ./models/*_audit.html }

# Softer gate — only fail when a specific flag appears

admeshio audit ./models --recursive | \

jq -r 'select(.flags[]?.code == "SELF_INTERSECTION") | .input.path' | \

tee failures.txt

test ! -s failures.txt

Exit code is derived from the audit result automatically — 0 when the mesh passed or only warned, 1 when the engine decided the mesh cannot be printed, or on a runtime error. The full GitHub Action + policy config (.admeshiorc.yml) is on the roadmap.

Slicer post-processing hook

Bambu Studio, OrcaSlicer, and PrusaSlicer all expose a Post-processing scripts setting that calls a binary after slicing. Wire admeshio verify into that hook and every slice gets audited before it leaves the slicer — no plugin to install, no upload step.

--recipe-from-3mf	Auto-resolve canonical profile from the gcode/3mf's embedded printer/material/quality metadata. Removes the need to pass `--recipe` manually for each slice.
--gate-on-fail <SCORE>	Exit non-zero when GRI-I drops below `SCORE` (0..100). The slicer surfaces this as a post-processing error so the user sees the failing slice instead of silently sending it to the printer.
--quiet, -q	Suppress info-level stderr (recipe matched, plate detected, verify complete). Errors and warnings still print so the slicer log stays readable.

Bambu Studio / OrcaSlicer / PrusaSlicer: Print Settings → Output options → Post-processing scripts. Paste the binary path and flags on a single line:

"C:\Program Files\AdMeshio\admeshio.exe" verify --recipe-from-3mf --gate-on-fail 70 --quiet

The slicer appends the sliced file path as the final argument automatically. A failing audit (GRI-I < 70 in the example above, or any engine error) flips the slicer's "Slicing completed" message to a red error referencing the post-processing script. The full JSON envelope still lands on stdout for any downstream tooling that wants the per-rule detail.

Cura uses a different post-processing API (Python plugin, not a subprocess hook). Native Cura support is on the roadmap.

REST API

HTTP service wraps the CLI. See the full API reference for request schemas, response headers, and SDK examples.

Primary endpoints

Method	Path	Description
POST	/v1/admeshio/audit	Returns admeshio-report/v1 envelope. HTTP 422 when the engine cannot evaluate the mesh.
POST	/v1/admeshio/verify	Returns v1 envelope for G-code. HTTP 415 on unknown format
POST	/v1/admeshio/repair	Upload STL → repair → download.
POST	/v1/admeshio/diagnose	Topology counters + intent openings.
GET	/v1/admeshio/catalog	Machine-readable capability spec (admeshio-catalog/v1)
GET	/health	Health check

Examples

# Audit a single mesh → admeshio-report/v1 envelope

curl -X POST http://localhost:8000/v1/admeshio/audit \

-F [email protected] -F recipe=bambu_x1c_pla_standard

# Repair a mesh

curl -X POST http://localhost:8000/v1/admeshio/repair \

-F [email protected] -o output.stl

# Verify G-code

curl -X POST http://localhost:8000/v1/admeshio/verify -F [email protected]

# Fetch the capability catalog (cache per session)

curl http://localhost:8000/v1/admeshio/catalog

SDKs (Python & C#)

Typed clients for the v1 envelope. Both SDKs auto-detect folder vs. single-file input and return AuditReport / list[AuditReport] accordingly.

Python

# pip install admeshio

import admeshio

# Audit (V1)

r = admeshio.audit("part.stl", recipe="bambu_x1c_pla_standard")

print(r["verdict"]["gri_overall"], r["verdict"]["bottleneck"]) # 87 readiness

# Repair

admeshio.repair("input.stl", "output.stl")

# Diagnose / thickness / diff / units

report = admeshio.diagnose("model.stl")

print(report["data"]["geometry"]["self_intersections"])

# Folder batch — list of envelopes

reports = admeshio.audit("./orders", recursive=True, workers=8)

weak = [r for r in reports if r["verdict"]["gri_overall"] < 60]

# Capability discovery

cat = admeshio.catalog()

for verb in cat.verbs: print(verb.name)

SDK exposes audit / verify / diagnose / repair / decimate / pipeline / diff / units / thickness / catalog.

Decimate & pipeline

# Decimate

admeshio.decimate("dense.stl", ratio=0.5, output="lite.stl")

# Chained pipeline (recipe as dict)

admeshio.pipeline("input.stl", recipe={

"name": "safe", "steps": [

{"op": "fix_si", "params": {"strict_quality": 1}},

{"op": "decimate", "params": {"ratio": 0.5}},

]}, output="ready.stl")

SDK works against the local binary (set ADMESHIO_BIN) or the hosted API. Same envelope shape either way.

Sample audit output

Download a real audit package generated by the current engine. Open the HTML report in your browser, inspect the JSON envelope, or upload the mesh to the web app.

admeshio-sample-audit.zip (315 KB) Download Sample

Contains: STL mesh + admeshio-report/v1 envelope (JSON) + full HTML visual report.

Profile: Bambu Lab A1 / PLA / Standard. Verdict: MANUAL REVIEW (65/100). Shows GRI-G/R/I breakdown, 42-check checklist, flagged issues with face IDs.

JSON envelope

Machine-readable. Contains verdict, GRI scores, stages, flags, billing. One parser for every verb.

HTML report

Human-readable. CI/CD style checklist with GRI-G/R/I tabs, heatmap, build progression, skip explanations.

Supported formats

Format	Import	Export	Best for
Mesh
STL (.stl)	Yes	Yes	Standard print workflows
3MF (.3mf)	Yes	Yes	Multi-part models, AMS/MMU color data
OBJ (.obj)	Yes	—	Object/group-based assets
GLB (.glb)	Yes	Yes	Compact scene, vertex colors, UV
glTF (.gltf)	Yes	—	JSON-based scene interchange
PLY (.ply)	Yes	Yes	3D scanning, point clouds, dental
Slicer output (FDM)
G-code (.gcode/.gco/.g)	Yes (`verify`)	Yes (`fdm-slice`)	OrcaSlicer / PrusaSlicer / Bambu / Cura output
Slicer output (resin / MSLA / DLP)
CTB (.ctb)	Yes (`verify`)	Yes (internal slicer)	CHITUBOX native, all CTB v3+ printers
cbddlp (.cbddlp)	Yes (`verify`, via UVtools)	—	Photon DLP / older CHITUBOX exports
pwmx (.pwmx)	Yes (`verify`, via UVtools)	—	Anycubic Photon Mono X family
pwmo (.pwmo)	Yes (`verify`, via UVtools)	—	Anycubic Photon Mono
goo (.goo)	Yes (`verify`, via UVtools)	—	Elegoo Saturn / Mars 4K+ family
Recommend INI (audit emit)
PrusaSlicer (.ini)	—	Yes (`--emit-fixed-profile out.ini`)	FDM & resin SLA — drop into PrusaSlicer Import Config
CHITUBOX (.cfg / .cfgx)	—	Yes (`--emit-fixed-profile out.cfg`)	Resin — Normal/Bottom Exposure, Lift/Retract Speed natively

UVtools dispatch (cbddlp / pwmx / pwmo / goo): admeshio invokes the UVtools CLI as a subprocess to extract layer PNGs, then runs the same Phase 2 raster checks (floating-island, vacuum-trap with 3D filter, peel-force spike) as the native CTB path. UVtools is not bundled — install separately and set ADMESHIO_UVTOOLS env var, or place at the standard path. Native CTB (.ctb v3+) needs no external dependency.

Quick Start

Commands

Repair

Automation

Quick Start

Audit a single file (geometry only)

Audit with printer profile

Audit + HTML report

Verify a sliced G-code (FDM)

Verify a sliced resin file (CTB / cbddlp / pwmx / goo)

Repair a broken mesh

Folder batch (auto-parallel)

Or use the web app (no install)

Example Output

All checks pass — mesh + user G-code

Mesh fails geometry — audit stops early

CLI exit codes

Command reference

Check & verify (read-only)

Repair & modify

Slice (uses your slicer)

Repair

What repair guarantees

Profiles, folder batch & automation

Printer profiles

Folder batch

Batch flags

CI / build pipeline integration

Slicer post-processing hook

REST API

Primary endpoints

Examples

SDKs (Python & C#)

Python

Decimate & pipeline

Sample audit output

Supported formats