MeshMagick         Manipulation tool for Ogre meshes and skeletons

Author: haffax with contributions by Blakharaz, Harlequin, Sinbad
Project: MeshMagick
Type: CommandLine Tool
Current version: 0.6
Licence: MIT
Status and bug reports: Forum topic
Code Repository: MeshMagick @ OgreAddons


MeshMagick is a manipulation tool for Ogre meshes (and skeletons) and is part of the OgreCommandLineTools. It allows the user to query interesting information and to transform binary meshes (and skeletons) in many ways. It can also be used as a library.

Info Remark: It's recommendable to add the path of the Ogre command-line tools into the path environment variable (on Windows systems). So you can use meshmagick in every directory.

Synopsis


meshmagick [global_options] toolname [tool_options] infile(s) [-- outfile(s)]

Included tools


info print information about the mesh
meshmerge Merge multiple meshes files into a single mesh file
optimise Optimise meshes and skeletons
rename Rename different elements of meshes and skeletons
transform Scale, rotate or otherwise transform a mesh

Global options


-help Prints this help text
-help=toolname Prints help for the specified tool
-list Lists available tools
-no-follow-skeleton Do not follow Skeleton-Link (if applicable)
-quiet Supress all messages to cout.
-verbose Print more detailed messages.
-version Print version number of meshmagick and Ogre


Help to some tools


optimise

Allows you to optimise meshes and skeletons. This will merge equal vertices, remove unneeded animation tracks and do other sensible optimisation operations, that can result in smaller mesh file size and better performance.

Options:

-tolerance=val Tolerance value for treating vertices as equal (all components)
-pos_tolerance=val Tolerance value for treating positions as equal
-norm_tolerance=val Tolerance value for treating normals as equal
-uv_tolerance=val Tolerance value for treating uvs as equal
-keep-identity-tracks When optimising skeletons, keep tracks which do nothing


rename

Rename different elements of meshes and skeletons.
All options can be used more than once to execute multiple renamings at once.
Instead of : any other non-space character part of neither new nor old name can be used as delimiter.

possible renamings:

-animation=:before:after: renames animation 'before' to 'after'
-bone=:before:after: renames bone 'before' to 'after'
-material=:before:after: change all materials 'before' to 'after'
-skeleton=newname renames mesh's skeleton to 'newname'
-submesh=:before:after: change name of submesh 'before' to 'after'


transform

Scales, rotates or otherwise transforms a mesh.
All transform options are applied in their relative order.

possible transformations:

-scale=x/y/z scale the mesh by this scale vector
-resize=x/y/z scale the mesh so, that its size is x/y/z.
-rotate=angle/x/y/z  rotate the mesh <angle> degrees on the axis x/y/z
-translate=x/y/z translate the mesh by this vector
-xalign=right;left;center align the mesh on x axis
-yalign=top;bottom;center align the mesh on y axis
-zalign=front;back;center align the mesh on z axis
-axes=x/y/z remaps main axes. e.g -axes=y/z/-x -------> x -> y, y -> z, z -> -x.


other options:

-flip-vertex-winding reorders indices to change the winding of vertices, turning the mesh inside-out.
-no-normalise-normals prevents normalisation of normals
-no-update-boundingbox keeps bounding box as defined in the file


Examples


Get informations about a mesh file:
meshmagick info filename.mesh

Optimizing a mesh file:
(do this - it's just a little mount of time)
meshmagick optimise filename.mesh

Are you as annoyed as I was when I started with Ogre? Robot and Ninja don't look into the same direction. The Ninja looks toward -Z, the Robot toward +X. Not any more! With a single command you can change the direction the robot looks:
MeshMagick transform -rotate=90/0/1/0 robot.mesh
(Make sure the skeleton is in the same directory as the mesh.)

A merging example:
meshmagick meshmerge input1.mesh input2.mesh input3.mesh — output.mesh

A rename example:
This renames the bone Joint1 to Bone1 in the ninja.skeleton and writes it back to the same file.
meshmagick rename -bone=:Joint1:Bone1: ninja.skeleton

Use with a global option for info:
meshmagick -no-follow-skeleton info input.mesh

Using MeshMagick as a library


Many of MeshMagick's tools can be used as a library too. This eases integration in editors or other applications where this functionality is needed. So far InfoTool, MeshMergeTool and TransformTool can be used as a library.

In order to use MeshMagick as a library do the following:


Here is a small code sample:

#include <MeshMagick.h>
 
 using namespace meshmagick;
 
 // Call this only after Ogre has been properly initialised.
 void scaleMesh(MeshPtr mesh, Vector3 scale)
 {
     MeshMagick mm;
     TransformTool* transformTool = mm.getTransformTool();
     transformTool->transform(mesh, Matrix4::getScale(scale), false);
 }