3d-file-toolkit

Inspect, edit, convert, and analyze 3D print files — pure Python, zero heavy dependencies.

Supports 3MF, STL, OBJ, PLY, and GLB. Detects which software made a file (Bambu Studio, Orca Slicer, PrusaSlicer, Cura, Fusion 360, etc.) and checks compatibility across 15 CAD and slicer programs. Works with any AI coding agent — Claude, Cursor, ChatGPT, Manus.

---

Install

One line:

pip install git+https://github.com/Kikobuf/3d-file-toolkit.git

Or clone:

git clone https://github.com/Kikobuf/3d-file-toolkit.git
cd 3d-file-toolkit
pip install numpy

Verify:

3dft --help

numpy is the only dependency. No trimesh, no VTK, no C extensions.

---

What it does

Command	What it does
3dft info <file>	Geometry stats, bounding box, metadata
3dft render <file> out.html	Interactive WebGL 3D viewer
3dft render <file> out.png	PNG thumbnail (pure numpy, no matplotlib)
3dft transform <file> out --scale 2.0	Scale / rotate / translate
3dft convert <file> out.glb	Convert between STL / 3MF / OBJ / PLY / GLB
3dft simplify <file> out --max-tris 10000	Reduce triangle count
3dft merge a.stl b.3mf -o merged.3mf	Combine multiple files
3dft split <file> -o part.stl	Extract one mesh from a multi-mesh file
3dft metadata <file> out --set Title="My Part"	Edit 3MF metadata
3dft metadata "*.3mf" --batch --set Designer=Me	Batch update metadata
3dft compat <file>	Detect source software + compatibility check

---

3D Viewer

Generate a self-contained interactive HTML viewer — no server, no internet required:

3dft render mymodel.3mf viewer.html

Multi-mesh files render each object in its own color. Drag to rotate, scroll to zoom, shift+drag to pan.

Works in Chrome, Firefox, Edge, and Safari. Touch-friendly for mobile. Falls back to basic shading automatically if the GPU doesn't support advanced WebGL extensions.

---

PNG Thumbnails

Render a shaded PNG preview with no external dependencies:

3dft render mymodel.3mf preview.png

   

Original 225k tris  →  Simplified to 50k  →  Simplified to 10k. Generated by the pure-numpy z-buffer renderer.

---

Format Conversion

Convert between any pair of supported formats:

3dft convert model.3mf model.stl    # for Thingiverse
3dft convert model.3mf model.obj    # for Blender / Sketchfab
3dft convert model.3mf model.ply    # for MeshLab
3dft convert model.3mf model.glb    # for web / AR viewers

     

Same benchy exported to STL, OBJ, PLY, and GLB — all from one command.

Supported formats:

• Read + write: .stl .3mf .obj .ply .glb
• Detected but not editable: .step .stp .iges .f3d .sldprt (CAD native — export from your CAD program first)

---

Simplify Heavy Meshes

Reduce triangle count for faster previews, smaller uploads, or web use:

3dft simplify mymodel.3mf lite.3mf --max-tris 10000
3dft simplify mymodel.3mf lite.stl --ratio 0.3

---

Check Compatibility

Detect what software made the file and see which programs will open it:

3dft compat benchy.3mf

Writer       : Bambu Studio
Extensions   : bambu_studio_namespace, production

Compatibility:
  ✓ Bambu Studio          (ok)
  ✓ Orca Slicer           (ok)
  ✓ PrusaSlicer           (ok)
  ✓ UltiMaker Cura        (ok)
  ✗ Simplify3D            (blocked) — Does not read .3mf, convert to .stl first
  ✗ Blender               (blocked) — Does not read .3mf, convert to .glb first
  ✗ Tinkercad             (blocked) — Does not read .3mf, convert to .stl first

---

3D Hosting Site Compatibility

Tested across major platforms:

Platform	Best Format	Notes
Printables.com	.3mf	Full metadata + multi-object preview
MakerWorld.com	.3mf	Full metadata + multi-object preview
Thingiverse.com	.stl	3MF accepted but STL gives more consistent previews
Sketchfab.com	.obj or .ply	Best geometry preservation in web renderer
Thangs.com	.stl	Standard STL works reliably
Cults3D.com	.3mf	Full support

---

Batch Metadata

Update metadata across an entire folder at once:

# Set designer on all 3MF files in a folder
3dft metadata "parts/*.3mf" --batch --set Designer="KB Rides" --set License="CC BY"

# Use a template JSON file
3dft metadata "*.3mf" --batch --template brand.json

Where brand.json looks like:

{
  "Designer": "KB Rides",
  "License": "CC BY 4.0",
  "Copyright": "2026 KB Rides"
}

---

Why it handles Bambu / Orca / Prusa files correctly

Most 3MF readers only parse 3D/3dmodel.model. Bambu Studio, Orca Slicer, and PrusaSlicer store actual geometry in sub-files (3D/Objects/object_1.model) referenced via <component p:path="...">. Naive tools see these as empty.

This toolkit walks the full build hierarchy and applies every transform in the chain — so files from any slicer just work.

---

Use as an AI Agent Skill

Works out of the box with any AI coding agent:

# Claude Code
git clone https://github.com/Kikobuf/3d-file-toolkit.git ~/.claude/skills/3d-file-toolkit

# Cursor — add scripts/ path to .cursor/rules/
# ChatGPT Code Interpreter — upload scripts/ folder
# Manus — clone to /opt/3d-file-toolkit

See docs/AGENTS.md for per-agent integration instructions.

---

Performance (225k-triangle 3DBenchy)

Operation	Time
info	~2.0s
render → html	~2.8s (5.4 MB self-contained viewer)
render → png	~6.0s (17 KB, pure numpy)
transform --scale 2	~4.6s
convert 3mf→stl	~2.1s
simplify --max-tris 10000	~2.5s

---

Stability

41 regression tests, all green on Linux / macOS / Windows × Python 3.9–3.12.

---

License

MIT. The included 3DBenchy test fixture is Daniel Norée's original file, released CC0 in April 2025.

Contributing

Good first issues: repair.py for mesh healing, quadric edge collapse decimation, 3MF color attribute support. Open an issue first. Keep the numpy + stdlib only constraint.