DOCS // meshfx

meshfx spec keys Available

meshfx spec keys, defaults and ranges come from the release schema. Use tree hierarchy for articulated assemblies.

Contents15 sections
  1. [meta]
  2. [source]
  3. [units]
  4. [pose]
  5. [repair]
  6. [retopo]
  7. [simplify]
  8. [lod]
  9. [uv]
  10. [textures]
  11. [bake]
  12. [export]
  13. [budget]
  14. [preview]
  15. Questions

meshfx runs on the hosted API: try it in the Playground.

Use the meshfx schema to set the source hierarchy, repair limits and LOD budgets. See the articulation guide for per-part limits and controller output.

weld settings

decimate settings

lod chain settings

uv pack settings

orm bake settings

convex hulls settings

[meta]

Names the model.

KeyValuesDefaultMeaning
namestring""Model name; used in every file name. Empty means the spec file's name.
seed0 to 42949672950Seed for every random choice.
notesstring""Free text.

[source]

The model to clean and its textures.

KeyValuesDefaultMeaning
filestring""The model: .glb, .gltf, .obj, .stl or .ply, beside or under the spec file. Missing is SOURCE_MISSING.
base_colourstring""An image that replaces the base colour map. Only for a model with one material.
normalstring""An image that replaces the normal map. Only for a model with one material.
metallicstring""A grey image that replaces the metal channel. Only for a model with one material.
roughnessstring""A grey image that replaces the roughness channel. Only for a model with one material.
occlusionstring""A grey image that replaces the occlusion map. Only for a model with one material.
emissivestring""An image that replaces the emissive map. Only for a model with one material.
normal_y+y, -y"+y"Which way green points in the source's normal maps. -y maps are turned to +y.
hierarchymerge, keep, tree"merge"merge: the whole file becomes one object. keep: each top-level node stays a separate object. tree: every node stays, with its name, its parent and its own place (rotation included); a node that draws a mesh keeps its own part, and an empty node stays as a pivot or socket where it sits in the tree.
kindauto, authored, scan, generator, generated"auto"Source provenance for repair defaults. auto uses UVs, assigned materials and normals. generated requires units.size_m and enables cleanup and pose defaults.
skinkeep, rest_pose, refuse"keep"For a skinned or animated model, choose keep to carry joint weights, skins and joint clips through every LOD, rest_pose to freeze it at rest without skin or clips, or refuse.
clean_namesbooltrueReplaces generator names such as Object_0 with names made from meta.name.
scene-1 to 1000-1Which scene of a glTF file. -1 is the one the file opens on.
splitnone, components, materials"none"Splits each object into objects of its own by connected part or by material, each its own node.
min_part_share0 to 0.50.01A split part smaller than this share of its object's area joins its nearest neighbour.

[units]

Size, up axis and origin.

KeyValuesDefaultMeaning
sourceauto, m, cm, mm, in, ft"auto"The unit the file is in. auto: metres for every format read so far.
size_m0 to 10000 m0Scales the model so size_axis measures this. 0 keeps the size.
size_axislargest, height"largest"What size_m measures.
upauto, y, z"auto"The source's up axis. auto: Y for every format read so far.
pivotbottom_centre, centre, keep, bottom_back, back_centre"bottom_centre"Where the origin goes. The back is the -Z face, once the model faces +Z.
pivot_offset_m-10000 to 10000 m[0,0,0]Added to the pivot after pivot is applied.

[pose]

Geometry-only humanoid pose checks.

KeyValuesDefaultMeaning
checkoff, auto, on"off"auto checks classified humanoids; on also reports missing evidence.
expecta_or_t, a_pose, t_pose"a_or_t"Accepted arm pose.

[repair]

Fixes to the surface (meshfx.md 5.3).

KeyValuesDefaultMeaning
enabledbooltrueOff skips repair. The faults are still counted and warned.
weld_m-1 to 1 m-1Vertices closer than this become one. -1 preserves authored vertices and otherwise picks 0.00001 of the diagonal. 0 welds only equal positions.
fix_windingbool or auto"auto"Makes each part face outward. auto preserves authored winding.
resolve_crossingsbool or auto"auto"Cuts intersecting facets. Opt-in for broken or scanned input: auto leaves crossings, unless remesh is always.
normalsauto, keep, recompute"auto"auto recomputes only normals that are missing or point against their face.
smooth_angle_deg0 to 180 deg60Recomputed normals are smooth across edges flatter than this.
fill_holesauto, none, small, all"auto"small fills only loops that pass the hole test; all also fills larger loops of solid parts and is opt-in. auto: none for authored input, small otherwise.
max_hole_share0 to 10.02A small hole's patch is at most this share of its part's area.
floatersauto, keep, detached"auto"auto keeps authored components and otherwise removes specks that pass all three floater tests.
floater_size0 to 0.50.02The speck is smaller than this share of the diagonal.
floater_gap0 to 10.05It is farther than this share of the diagonal from everything else.
remove_hiddenbool or auto"auto"auto considers removal above 10% hidden faces. Checks all 14 source silhouettes.
remeshnever, auto, always"never"Rebuilds solid parts as one closed surface.
remesh_voxel0 to 0.10Cell size of the rebuild, as a share of the diagonal. 0 picks 1/512 at final, 1/256 at draft.
thicken_m0 to 10 m0Above 0, an open sheet is given this thickness and becomes a closed shell.
max_error0 to 0.10.002A repair step that moves the surface farther than this share of the diagonal is undone.

[retopo]

Stage 9 editing mesh.

KeyValuesDefaultMeaning
modeoff, quads, quad_dominant"off"An enabled mode requests stage 9. Articulated inputs refuse retopology.

[simplify]

Triangle reduction of LOD0 (build stage 3).

KeyValuesDefaultMeaning
triangles0 to 1000000010000Triangle budget of LOD0, the whole asset. 0 keeps every triangle.
max_error0 to 0.50.02Warn when the written level exceeds this surface error (share of the diagonal).
protectborders, material_edges, hard_edges, uv_seams, colour_edges["borders","material_edges"]Edges that must survive.
forbidopen_edges, non_manifold_edges, crossings["open_edges"]Faults a level may not add beyond the repaired model's. Others are counted in each level's metrics.
attribute_weight0 to 40.5How much normals, UVs and colour count against position.

[lod]

Detail levels (build stage 3).

KeyValuesDefaultMeaning
count0 to 80Detail levels, LOD0 included. 0 takes the target's default.
ratio0.05 to 0.90.5Each level's triangles as a share of the level before.
triangleslist of integers[]Explicit budgets for LOD1 onward, each 4 to 10000000, falling.
max_error0 to 0.50.08Error limit for the last level (share of the diagonal).
pixel_error0.1 to 16 px1A level is used from the distance where its error is this many pixels.

[uv]

UV sets.

KeyValuesDefaultMeaning
modeauto, keep, unwrap, repack"auto"keep: the source UVs. unwrap: new charts. repack: the source charts packed again. auto: keep when they pass the checks of LOD0 and no materials are merged, repack when they pass and the atlas merges materials, else unwrap.
padding_px0 to 64 px4Empty texels between charts at textures.size_px.
iterations1 to 82Chart-growing passes.
lightmapboolfalseAlso writes a second UV set with no overlap, for baked lighting.
time_limit_s1 to 3600 s120Unwrapping stops after this and the plain method is used.

[textures]

Baked texture set.

KeyValuesDefaultMeaning
size_px64 to 8192 px2048Edge of each baked texture at final. Draft halves it.
atlasauto, single, per_material"auto"auto keeps usable authored charts and merges materials when an unwrap is needed. single merges materials per alpha kind.
mapsbase_colour, normal, metallic_roughness, occlusion, emissive, curvature, mask["base_colour","normal","metallic_roughness","occlusion","emissive"]Maps to write. A map the source lacks is left out, except normal with bake.source_detail. curvature and mask are written beside the model and named in layout.json.
ktx2_qualityhigh, small"high"high: UASTC. small: ETC1S for colour maps.
colourtexture, vertex, flat, none"texture"Where base colour goes. vertex: baked to vertex colour, no colour map. flat: one colour a material, the mean over its area. none: white. Any value but texture takes the place of bake.vertex_colour.
mask_rzero, one, occlusion, roughness, metallic, edge_wear, cavity"occlusion"What the mask map's red channel holds. edge_wear and cavity are the halves of the curvature map.
mask_gzero, one, occlusion, roughness, metallic, edge_wear, cavity"roughness"What the mask map's green channel holds.
mask_bzero, one, occlusion, roughness, metallic, edge_wear, cavity"metallic"What the mask map's blue channel holds.
mask_azero, one, occlusion, roughness, metallic, edge_wear, cavity"one"What the mask map's alpha channel holds.
texel_density0 to 4096 px/m0Above 0 it picks size_px from the surface area (at most size_px), so props of different sizes match.
delightoff, auto, on"off"Takes shading painted into base colour back out. auto acts only when the colour's brightness follows the shading predicted from normals and occlusion more closely than delight_threshold.
delight_threshold0 to 10.5The correlation delight = auto needs.
pbr_checkoff, report, fix"report"report measures the share of texels outside albedo_range and with metallic between 0 and 1. fix clamps colour and snaps metallic.
albedo_range0 to 255 sRGB[30,240]The base colour range pbr_check uses.
metallic_snap0 to 0.50.1With pbr_check = fix, metallic within this of 0 or 1 becomes 0 or 1.

[bake]

Texture bake from the source.

KeyValuesDefaultMeaning
source_detailbooltrueThe normal map carries the source's shape that reduction removed.
max_distance0.0001 to 0.50.02How far from the new surface the source is searched (share of the diagonal).
samples1 to 164Samples a texel at final. Draft uses 1.
occlusionoff, source, compute"source"source carries the source's occlusion map; compute traces it.
occlusion_rays8 to 102464Rays a texel for compute.
vertex_colourto_texture, keep, drop"to_texture"to_texture multiplies vertex colour into the base colour map.
dilate_px0 to 64 px16How far each chart's colour is spread into the gap around it.

[export]

Output folders, one a target.

KeyValuesDefaultMeaning
targetsgodot, unity, unreal, roblox, threejs["godot"]One output folder each. A target whose build stage is not in this program fails with STAGE_FAILED; `targets` in the schema output says which are built.
compressiontarget, none, meshopt"target"Mesh compression in a GLB. none: no compression and no KHR_mesh_quantization, every attribute plain floats.
lod_layouttarget, nodes, files"target"LODs as nodes of one file, or one file a level.
textures_intarget, embedded, beside"target"Textures inside the model file or as files beside it.
forwardtarget, +z, -z, +x, -x"target"Which way the front points in the written file. target is the target's rule.
name_styletarget, keep, lower_snake"target"Names of nodes, meshes and materials in the file: the target's rule, as they are, or lower_snake.

[budget]

Limits a bake must meet; a missed one fails it with BUDGET_EXCEEDED (exit 5), files still written.

KeyValuesDefaultMeaning
max_triangles0 to 100000000Most triangles in LOD0, the whole asset; LOD0 aims at it. 0 sets no limit, here and below.
max_materials0 to 640Most materials. 1 also makes textures.atlas single and merges opaque, cut-out and blended surfaces into one material.
max_texture_px0 to 8192 px0Caps textures.size_px and the edge of every texture written.
max_bytesintegerLargest output folder a target. Textures are halved until it fits or they reach 64 px.
fail_onNON_MANIFOLD_EDGES, FLIPPED_NORMALS, OPEN_HOLES, DUPLICATE_VERTICES, ZERO_AREA_FACES, BAD_SCALE, POSE_NOT_READY, WRONG_PIVOT, UV_OVERLAP, UV_OUT_OF_RANGE, UV_STRETCH_HIGH, UV_FALLBACK, TEXEL_DENSITY_LOW, SELF_INTERSECTIONS, HIDDEN_GEOMETRY, JOINT_PART_FLOOR, JOINT_NORMAL_NEEDS_UV, FLOATERS_REMOVED, REPAIR_REJECTED, NOT_WATERTIGHT, ZERO_THICKNESS, LOD_BUDGET_MISSED, SILHOUETTE_CHANGED, PART_LOST, LOD_FAULTS_ADDED, BAKE_MISSES, BAKE_MISMATCH, BAKED_LIGHTING, ALBEDO_OUT_OF_RANGE, TEXTURE_DOWNSIZED, MATERIAL_SIMPLIFIED, ATTRIBUTE_DROPPED, ANIMATION_DROPPED, COLLISION_LOOSE, COLLISION_CAPPED, OCCLUDER_SKIPPED, STAGE_NOT_BUILT[]Warning codes: a bake that ends with one of them fails.

[preview]

The preview images.

KeyValuesDefaultMeaning
thumbnail_px64 to 1024 px256Edge of preview_thumb.png: LOD0 from the corner on a transparent background.

Questions

How does source.hierarchy control objects in a meshfx spec?

Set merge to combine objects, keep to preserve top level nodes or tree to keep every node, parent and pivot.

What happens when source.skin is set to keep on an animated model?

meshfx carries joint weights, skins and joint clips through every level of detail instead of freezing the model at rest.

When is units.size_m required in a meshfx spec?

You must set units.size_m when source.kind is set to generated so meshfx can scale the model and run cleanup.