History: MeshMagick

• «
• »

            __Author:__ haffax - blakharaz
__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]

---
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.

__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 submeshes into a single mesh
__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

!!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] 
* Most recent source code in the [https://ogreaddons.svn.sourceforge.net/svnroot/ogreaddons/trunk/meshmagick/|ogreaddons repository]