History: MeshMagick

            __Author:__ haffax with contributions by Blakharaz, Harlequin, Sinbad
__Project:__ MeshMagick 
__Type:__ CommandLine Tool
__Current version:__ 0.6
__Licence:__ [http://www.opensource.org/licenses/mit-license.php|MIT]
__Status and bug reports:__ [http://www.ogre3d.org/phpBB2/viewtopic.php?t=32352|Forum topic]
__Code Repository:__ [https://github.com/OGRECave/meshmagick|Github]

---
MeshMagick is a __manipulation tool__ for Ogre meshes (and skeletons) and is part of the [http://www.ogre3d.org/download/tools|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.

%note% __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.

{maketoc}

!!Synopsis
---
{MONO()}~np~meshmagick [global_options] toolname [tool_options] infile(s) [-- outfile(s)]~/np~{MONO}

!!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:
{MONO()}meshmagick info ''filename''.mesh{MONO}

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

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:
{MONO()}MeshMagick transform -rotate=90/0/1/0 robot.mesh{MONO}
(Make sure the skeleton is in the same directory as the mesh.)

A merging example:
{MONO()}meshmagick meshmerge input1.mesh input2.mesh input3.mesh -- output.mesh{MONO}

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

Use with a global option for info:
{MONO()}meshmagick -no-follow-skeleton info input.mesh{MONO}

!!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:
* Get source from [https://ogreaddons.svn.sourceforge.net/svnroot/ogreaddons/trunk/meshmagick]
* Compile it
* Include header file MeshMagick.h and link to meshmagick.lib/meshmagick_d.lib/meshmagick.so depending on your platform.

Here is a small code sample:
{CODE(wrap="1", colors="c++")} #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);
 }{CODE}


!!Links
---
* Discussion and more information at the [http://www.ogre3d.org/phpBB2/viewtopic.php?t=32352|Forum topic].
* MeshMagick is included in the Ogre [http://www.ogre3d.org/download/tools|command-line tools] ''(warning: this version can be extremely old!)''
* Most recent source code in the [https://bitbucket.org/ogreaddons/meshmagick|MeshMagick @ OgreAddons]
* [http://www.ogre3d.org/forums/viewtopic.php?p=410965#p410965|Download] of MeshMagick compiled against Ogre __1.7.1__