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

Badges	Certificate

🔌 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.38.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.38.0
        with:
          command: scan
          image-tag: "3.38.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).

# Validate a specific mesh
- uses: fernandotonon/QtMeshEditor@3.38.0
  with:
    command: validate
    input-file: ./models/character.fbx
    image-tag: "3.38.0"

# Convert FBX → glTF
- uses: fernandotonon/QtMeshEditor@3.38.0
  with:
    command: convert
    input-file: ./models/character.fbx
    output-file: ./output/character.gltf2
    image-tag: "3.38.0"

# Resample Mixamo animations (200+ keyframes → 30)
- uses: fernandotonon/QtMeshEditor@3.38.0
  with:
    command: anim
    input-file: ./animations/dance.fbx
    output-file: ./output/dance_optimized.fbx
    options: --resample 30
    image-tag: "3.38.0"

# Get mesh info as JSON
- uses: fernandotonon/QtMeshEditor@3.38.0
  id: info
  with:
    command: info
    input-file: ./models/character.fbx
    options: --json
    image-tag: "3.38.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

1. Sign in at qtmesh.dev and create a project.
2. Create a project token in QtMesh Cloud.
3. Add the token as a GitHub secret named QTMESH_CLOUD_TOKEN.
4. Run the scan command from Github Actions example above.

Badge markdown (replace <owner-slug> and <project-slug>):

[![qtmesh status](https://api.qtmesh.dev/v1/u/<owner-slug>/p/<project-slug>/badges/qtmesh-status.svg)](https://qtmesh.dev)
[![qtmesh errors](https://api.qtmesh.dev/v1/u/<owner-slug>/p/<project-slug>/badges/qtmesh-errors.svg)](https://qtmesh.dev)
[![qtmesh warnings](https://api.qtmesh.dev/v1/u/<owner-slug>/p/<project-slug>/badges/qtmesh-warnings.svg)](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

🎨 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):

1. Switch to Material Mode (mode bar at the top).
2. 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.
3. 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).
4. 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.
5. 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).
6. 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
• 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)
• AI chat — natural language scene editing via local LLMs
• MCP server — 57+ tools for AI agents (Claude, Cursor, etc.), including HDR/IBL (set_hdr_environment, set_tonemap, …) and QtMesh Cloud (cloud_*)
• REST API — HTTP interface for external automation

📦 Install

📥 Download latest release · 📖 Website & docs

📋 Format Support

.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