QtMeshEditor
Automate your 3D asset pipeline — scan, validate, convert, fix, and merge 3D assets with GUI + CLI + CI/CD support.
Open 3D files from your OS — after install, double-click .fbx, .glb, .gltf, .obj, .dae, .stl, .ply, .mesh, and PS1 .rsd/.tmd in Finder, Explorer, or your Linux file manager (or use Open With). QtMeshEditor loads the model in the running window; a second launch focuses the existing instance instead of spawning another process. Portable Windows ZIP users can run bin/scripts/register-windows-file-associations.ps1 to register handlers without admin rights.
Star if you like it!
QtMesh Cloud Badges
🔌 CI/CD — GitHub Actions
Available on the GitHub Actions Marketplace.
Versioning
- Always follow the latest GitHub release — use the Marketplace floating tag
fernandotonon/QtMeshEditor@v1 (same pattern as the Marketplace example). The composite action defaults to image-tag: latest, so the Docker CLI tracks the newest published ghcr.io/fernandotonon/qtmesh image.
- Reproducible builds — pin the action and the container to the same semver as this repository’s
project(QtMeshEditor VERSION …) in CMakeLists.txt (currently 3.46.0). After bumping the version in CMake, run ./scripts/sync-doc-versions-from-cmake.sh to refresh the pinned refs in README.md and the docs site fallback; CI enforces the match with ./scripts/sync-doc-versions-from-cmake.sh --check.
Pinned workflow template (action + ghcr.io image aligned):
name: QtMesh Scan
on:
push:
branches: [ "master" ]
jobs:
scan-assets-qtmesh:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run QtMesh scan
uses: fernandotonon/QtMeshEditor@3.46.0
with:
command: scan
image-tag: "3.46.0"
env:
QTMESH_CLOUD_TOKEN: ${{ secrets.QTMESH_CLOUD_TOKEN }}
Floating ref (auto-updates when the v1 tag moves on release):
- name: Run QtMesh scan
uses: fernandotonon/QtMeshEditor@v1
with:
command: scan
QTMESH_CLOUD_TOKEN is forwarded into the container and used by scan upload. GitHub Actions metadata (GITHUB_*) is also forwarded so uploads include meta fields (branch/commit/run and context used by QtMesh Cloud).
To fail CI when upload fails, add qtmesh-strict-upload: true (or pass --strict-upload in options).
Release tags are listed on the releases page (also referenced in QtMesh Cloud onboarding).
More CI examples
# Validate a specific mesh
- uses: fernandotonon/QtMeshEditor@3.46.0
with:
command: validate
input-file: ./models/character.fbx
image-tag: "3.46.0"
# Convert FBX → glTF
- uses: fernandotonon/QtMeshEditor@3.46.0
with:
command: convert
input-file: ./models/character.fbx
output-file: ./output/character.gltf2
image-tag: "3.46.0"
# Resample Mixamo animations (200+ keyframes → 30)
- uses: fernandotonon/QtMeshEditor@3.46.0
with:
command: anim
input-file: ./animations/dance.fbx
output-file: ./output/dance_optimized.fbx
options: --resample 30
image-tag: "3.46.0"
# Get mesh info as JSON
- uses: fernandotonon/QtMeshEditor@3.46.0
id: info
with:
command: info
input-file: ./models/character.fbx
options: --json
image-tag: "3.46.0"
# Docker (alternative — :latest tracks newest image; pin :3.4.0 to match semver action ref)
# The image is multi-arch (linux/amd64 + linux/arm64), so it runs natively on
# both Intel and Apple Silicon Macs — no --platform flag or QEMU needed.
docker run --rm -v $(pwd):/workspace ghcr.io/fernandotonon/qtmesh:latest scan ./assets --fail-on error
☁️ QtMesh Cloud Badges
- Sign in at qtmesh.dev and create a project.
- Create a project token in QtMesh Cloud.
- Add the token as a GitHub secret named
QTMESH_CLOUD_TOKEN.
- Run the scan command from Github Actions example above.
Badge markdown (replace and):
[](https://qtmesh.dev)
[](https://qtmesh.dev)
[](https://qtmesh.dev)
🔧 CLI Pipeline (qtmesh)
Same commands locally, in Docker, or in CI:
# Scan a directory for asset issues
qtmesh scan ./assets --fail-on warning
qtmesh scan ./assets --json --report report.json
# Inspect a mesh
qtmesh info model.fbx --json
# Validate geometry
qtmesh validate model.fbx
# Convert between formats
qtmesh convert model.fbx -o model.gltf2
# Convert + Draco-compress the glTF (smaller .glb; needs a Draco-enabled build)
qtmesh convert model.fbx -o model.glb --compress draco
# Fix / optimize
qtmesh fix model.fbx -o fixed.fbx --all
# Animation tools
qtmesh anim model.fbx --list
qtmesh anim model.fbx --rename "Take 001" "Idle" -o renamed.fbx
qtmesh anim model.fbx --resample 30 -o optimized.fbx
qtmesh anim base.fbx --merge walk.fbx run.fbx -o merged.fbx
# Export animation pose as static mesh (3D printing)
qtmesh pose model.fbx --animation "Dance" --count 4 -o pose_%02d.stl
# LOD generation
qtmesh lod model.fbx --auto
# Bake vertex colors → texture (with UV-seam dilation)
qtmesh bake-vertex-colors model.fbx -o color_map.png --resolution 1024 --dilation 4
qtmesh paint-bake model.fbx --target unreal -o out/ # repack the mesh's PBR textures into an engine layout + sidecar JSON
qtmesh paint-bake model.fbx --target unity -o out/ --resolution 2048 --prefix hero # Unity: metallic+smoothness RGBA, DirectX (+Y down) normal
qtmesh paint-bake --list-targets # generic | unity | unreal | godot | gltf
qtmesh paint --list-stamps # brush stamps (also --list-presets, --list-palettes; all take --json)
qtmesh paint model.fbx --layer list --json # paint layers (layers are a live-session concept; bake to write pixels)
qtmesh paint model.fbx --bake --engine unity -o out/ # alias of paint-bake --target
qtmesh paint model.fbx --apply-stencil decal.png --camera "0,1,4,0,1,0" -o out.mesh # project an image through an explicit camera
# Auto UV unwrap (xatlas — same library Blender/Godot use)
qtmesh uv model.fbx --unwrap -o unwrapped.glb # overwrite UV0
qtmesh uv model.fbx --unwrap --channel 1 -o lightmap.glb # keep UV0, write UV1 (lightmap workflow)
qtmesh uv model.fbx --info --json # report UV channels + coverage
# Quad retopology (triangle-pairing — no new deps)
qtmesh retopo model.fbx -o quads.glb # pair every viable triangle into quads
qtmesh retopo model.fbx --target-faces 5000 -o lo.glb # stop early once near target face count
qtmesh retopo model.fbx --max-angle 15 -o conservative.glb # tighter coplanarity gate
# Compute skin weights (inverse-distance heuristic; mesh must have a skeleton)
qtmesh skin model.fbx -o skinned.glb # default 4 influences, falloff 4
qtmesh skin model.fbx --max-influences 8 --falloff 6 -o skinned.glb
qtmesh skin model.fbx --skip-unweighted --merge -o filled.glb # fill missing weights only
# Auto-generate the 52 ARKit blendshapes on a humanoid FACE mesh (for face capture)
qtmesh facerig head.glb -o rigged.glb # fit ARKit template + transfer 52 shapes
qtmesh facerig head.fbx -o rigged.glb --max-shapes 20 --json # cap shapes / machine-readable report
# Drive those blendshapes from SPEECH (NVIDIA Audio2Face-3D, runs locally)
qtmesh lipsync take.wav --mesh head.glb -o spoken.glb # audio -> ARKit weight animation
qtmesh lipsync take.wav --mesh head.glb --fps 60 --clip Speech -o out.glb
qtmesh lipsync take.wav --mesh head.glb --emotion joy=0.6 -o out.glb
# Retarget a clip onto a different skeleton (auto bone map, or a bundled / .bonemap map)
qtmesh anim mixamo_walk.fbx --retarget hero.glb --bonemap mixamo_to_unity --anim Walk -o hero_walking.glb
# Vertex Animation Textures (OpenVAT) — four modes, one baker
qtmesh vat character.fbx --anim Walk --fps 30 -o walk_vat/ # skeletal: per-vertex positions + normals (Godot/Unity/Unreal shaders in tools/vat-shaders/)
qtmesh vat pieces.fbx --anim Explode --mode rigid --target godot -o out/ # rigid-body: one quaternion + pivot per submesh chunk (destruction / mechanical), ships openvat_rigid.gdshader
qtmesh vat cache.abc --mode mesh-anim --anim Cache -o out/ # vertex cache (Alembic / VAT_POSE clip)
qtmesh vat face.glb --mode morph --encoding exr -o out/ # keyed morph weights (default clip "MorphAnim"), float32 EXR; --encoding rgba8|rgba16|exr
🎨 Paint Tools
ZBrush-style polypaint and full PBR channel texture painting — Base Color,
Normal, Roughness, Metallic, AO and Emissive — with a 2D preview panel,
multiple brush tools (paint, erase, fill, color picker, smudge), layers, a
channel picker, channel-aware presets (scratches into roughness, emissive
sparks, edge wear, dirt build-up, sticker), and a one-click bake that turns
vertex colors into a UV-space texture. Every bake merges with the slot's
existing texture rather than overwriting it — scalar channels collapse into
their lane of the packed ORM map, and Normal-channel sculpts Sobel-convert to a
tangent-space normal and blend onto the existing normal map, all rendering live
under IBL. Symmetry mirrors every stroke in real time across the local or
world X/Y/Z planes (combine axes for 4- or 8-way mirroring; a topology-aware
mode keeps mirrors correct on meshes with an asymmetric UV unwrap), and a
line stabilizer (moving-average or trailing) smooths mouse jitter for clean
strokes. Projection painting projects an image onto the mesh through the
camera — brush through a stencil, lock the projection to a camera pose, or
project a photo straight onto the visible surface (with backface culling,
depth-limit and per-texel occlusion so it only lands where the camera can see);
and the decal tool drops a placeable image rectangle (drag to move / rotate
/ scale, Enter to commit) onto the surface. Each projection lands in its own
layer.
Quick start (texture paint, GUI):
- Switch to Material Mode (mode bar at the top).
- Select a mesh entity. The Inspector's Texture Paint section
shows a slot picker (every paintable TUS across submeshes) and a 256×256
live preview of the active texture.
- Click the paint brush button in the toolbar to enable painting. The
first click on the mesh auto-creates a paint session against the active
slot (or you can pre-create with Create / Attach Texture).
- Pick a tool from the row at the top of the panel: ✏ Paint, ⌫ Erase, ⧉ Fill,
⊰ Pick (eyedropper), ∿ Smudge. Brush color/radius/strength/falloff comes
from the shared Paint Brush section above the toolbar's brush popup.
- Left-click-drag on either the 3D mesh or the 2D preview panel. Both
drive the same paint buffer; the 2D preview updates in real time and a
brush ring shows where the cursor maps on the 3D surface (and vice versa).
- Save… / Load… round-trips the buffer to disk as PNG (or any format
QImage can write).
Vertex paint (GUI):
Same flow, but vertex paint operates in Edit Mode instead. Press Tab
on a selected mesh to enter Edit Mode, then tick Vertex Color Preview in
the Edit Mode Tools section to see vertex colors live.
Bake Vertex Colors → Texture rasterizes the active mesh's vertex colors
into a UV-space PNG via barycentric interpolation, then dilates the result
outward by N pixels to mask UV-seam bleed at MIP-map time.
Headless (CLI):
qtmesh bake-vertex-colors model.fbx -o color_map.png --resolution 1024 --dilation 4
qtmesh paint-bake model.fbx --target unreal -o out/ # repack the mesh's PBR textures into an engine layout + sidecar JSON
qtmesh paint-bake model.fbx --target unity -o out/ --resolution 2048 --prefix hero # Unity: metallic+smoothness RGBA, DirectX (+Y down) normal
qtmesh paint-bake --list-targets # generic | unity | unreal | godot | gltf
qtmesh paint --list-stamps # brush stamps (also --list-presets, --list-palettes; all take --json)
qtmesh paint model.fbx --layer list --json # paint layers (layers are a live-session concept; bake to write pixels)
qtmesh paint model.fbx --bake --engine unity -o out/ # alias of paint-bake --target
qtmesh paint model.fbx --apply-stencil decal.png --camera "0,1,4,0,1,0" -o out.mesh # project an image through an explicit camera
Export. Vertex colors are preserved on export to formats that support
them (glTF preferred — verified round-trip).
Notes / limitations.
- Brush size is in local mesh units (shared with vertex paint). For texture
paint we divide by mesh bounding-box extent and clamp to a UV-friendly
range, so 0.25 produces a sensible stamp on both a unit cube and a
100-unit character.
- Painting auto-rebinds every TUS named
albedo or diffuse_map on the
active material — imported PBR materials alias the diffuse texture under
both, and rebinding only one would leave the other pointing at the
original.
- Bake uses fan triangulation of n-gon faces; concave faces should be
pre-triangulated.
✨ Merge Mixamo Animations in Seconds
Download animations from Mixamo, drop them into QtMeshEditor, and merge into a single file — export as glTF, FBX, Collada, OBJ, or Ogre Mesh.
🎬 More in Action
| Split View | Skeleton Animation Controls |
|---|
 |  |
| MCP tools (AI Agent Control) | Bone Weight Visualization |
 |  |
🤖 AI-enhanced Material Editor
🎮 Features
- Asset scanning — ESLint for 3D assets: check naming, complexity, skeletons, formats
- QtMesh Cloud — sign in, upload asset projects (model + textures + materials + animations), browse/open from qtmesh.dev; CLI (
qtmesh cloud …) and MCP (cloud_* tools) parity
- 40+ format support — FBX, glTF, OBJ, Collada, STL, Ogre Mesh, and more
- Animation merge — combine Mixamo clips into one file
- Animation resampling — reduce keyframe density for game engines
- Pose export — bake animation frames as static meshes (3D printing)
- LOD generation — automatic level-of-detail mesh reduction
- Paint tools — vertex paint, texture paint (BaseColor), bake vertex colors to texture with seam dilation
- Material editor — visual editing with AI-assisted generation; PBR + HDR/IBL materials look correct on first import (bundled studio HDRI, ACES tonemap, env intensity/tint per material)
- Skeleton inspection — bone weights, debug overlays, animation preview
- Lattice deformer — Blender-style lattice modifier: box a mesh with a grid of control points and drag them in the viewport to bend, squash or stretch it (linear / smooth / Bézier interpolation, live preview, one-step undo); save the lattice and replay it with
qtmesh lattice --apply -o or MCP lattice_begin / lattice_set_points / lattice_apply / lattice_deform
- AI part segmentation & PartOps — detect a character's parts (head/torso/arms/legs), then split into named submeshes, explode into separate scene nodes, join them back, or solidify thin-shell parts; GUI +
qtmesh segment --split-parts / --explode-parts + MCP (split_mesh_by_segments, explode_mesh_parts, join_mesh_parts) — see docs/PART_OPS.md
- Scene management — duplicate (Ctrl+D), group (Ctrl+G), snap, pivot modes
- Performance capture — video/webcam → facial morph animation (ARKit blendshapes), head pose, and full-body skeletal capture onto humanoid rigs; live preview + record in the editor,
qtmesh mocap on the CLI (-DENABLE_MOCAP builds)
- Audio-driven lipsync — speech → ARKit blendshape animation via NVIDIA's Audio2Face-3D, running locally through ONNX; drives any mesh with ARKit targets (including the ones
qtmesh facerig generates), in the Inspector, qtmesh lipsync on the CLI, or the generate_lipsync MCP tool
- AI agent — describe a task in natural language; a local LLM plans it over the editor's tools, runs it step by step with structured observations and replanning, groups it into ONE undo step, and asks before deleting or overwriting (agent mode; the simple chat loop is one click away)
- MCP server — 57+ tools for AI agents (Claude, Cursor, etc.), including HDR/IBL (
set_hdr_environment, set_tonemap, …) and QtMesh Cloud (cloud_*)
- REST API — opt-in HTTP interface for external automation (
--with-mcp --http-port 8080). Bound to localhost by default; tools execute only via POST /api/tools/ (GET /api/tools lists them); set QTMESH_HTTP_TOKEN (or --http-token-file ; a secret on the command line is refused, since ps shows it to every local user) to require Authorization: Bearer on every request, and --http-bind 0.0.0.0 only when you mean to expose it
📦 Install
| Platform | Command |
|---|
| Windows | winget install FernandoTonon.QtMeshEditor |
| macOS | brew tap fernandotonon/qtmesheditor && brew trust fernandotonon/qtmesheditor && brew install qtmesheditor |
| Linux | sudo snap install qtmesheditor |
| Docker | docker run --rm ghcr.io/fernandotonon/qtmesh --help |
📥 Download latest release · 📖 Website & docs
📋 Format Support
| Format | Extension | Import | Export | Skeleton/Animation |
|---|
| FBX Binary | .fbx | ✅ | ✅ | ✅ |
| glTF 2.0 | .gltf2 / .glb2 | ✅ | ✅ | ✅ |
| Collada | .dae | ✅ | ✅ | ✅ |
| OBJ | .obj | ✅ | ✅ | — |
| STL | .stl | ✅ | ✅ | — |
| Ogre Mesh | .mesh / .mesh.xml | ✅ | ✅ | ✅ |
| PlayStation TMD | .tmd | ✅ | ✅ | — |
| PlayStation RSD | .rsd | ✅ | ✅ | — |
| 3DS | .3ds | ✅ | ✅ | — |
| Stanford PLY | .ply | ✅ | ✅ | — |
| Psy-Q PLY (PlayStation) | .ply | ✅ | ✅ | — |
.ply is dispatched by content: Stanford (ply header) vs Psy-Q (@PLY… header). See documentation/playstation-rsd-ply.md.
Import supports all formats provided by Assimp (40+).
📖 Documentation · 🛠 Build from source · 🐛 Report issues · 💬 Contribute
