|
|
QSDK 1.1 Documentation |
|
|
Click on the links below to go directly to the topic of interest
for Maya version 2.5.
Use "maya3ToQ", "maya4ToQ", "maya45ToQ" or "maya5ToQ" for later versions of Maya.
-h or -? Displays an 'about' usage message line and exits
-v Sets Verbose debug messages.
Warning and Error messages are always directed to stderr. Extra informational and Debug messages are directed to stdout if verbose is selected. Log messaging must also be enabled for 'exporter' category messages (see QSettings)
-r Sets a right handed coordinate system for the export.
By default, the scene is converted using a left-handed coordinate system (which is the default for QServer). Most users will not need to use this option.
-c Use centimetres as metre units, default is metres.
The default units for Q are metres and we recommend that the Maya user-interface is also set to use metres in which case a one-unit length in Maya translates to a one-unit length in Q. The default user-interface unit in Maya, however, is centimetres and this can cause problems. For instance a one hundred-unit length in Maya would be translated to a one-unit length in Q. If this is not what is required, then this option can be used to suppress the conversion from centimetres to metres. The result will be that one centimetre in Maya will export as one metre in Q.
-s Display the skeleton for a skin. This option will cause a representation of the skeleton to be exported, which can be useful for debugging purposes.
-t Sample animations frame by frame rather than the default which is by key frames. This can give a more accurate representation of animations but there may be an overall speed trade off in complex scenes. See also the Heart Text File setting
-q <value> This sets the Animation sampling Epsilons to preset qualities. 'value' is an integer in the range 1 through to 5. Quality 1 is the widest sampling error, and quality 5 is the narrowist. Quality 3 is the default. -b <base file> The fully qualified location of the base 'q' file
-j <joint limit> Sets the maximum skin joint influences per Vertex. The absolute limit is 4.
-k <joint limit> Sets the maximum joint influences per skin. The default is to have no limit. For content to be used on Playstation II, a limit of 64 should be used. -f <batch file> Use a text file to read the Maya file names for batch export.
Batch processing of multiple Maya files is achieved by the exporter reading the text 'batch file' which should contain a list of fully qualified Maya filenames, one per line. Note that if using '\' in the file name then this must be entered as '\\'. For example the file name 'c:\mydirectory\myMayaFile.ma' must be entered as 'c:\\mydirectory\\myMayaFile.ma'
The mayatoq utility will then process each file in turn.
-o <output file> Specify the output .q file. If this is used with the Batch processing option then it will only be effective for the first file output, subsequent names will be based on the root name of the Maya file as explained below.
-d <tex path> Use this option once for each texture path to add to the search list. If a texture cannot be located in the path given in the maya file the set of texture paths will be searched. -z <zoneName> By default the scene is exported to zone tempZone. By setting this option you can export to a specified zone name. This is useful in production builds to avoid duplicate names. -nocameras Causes the exporter not to create any cameras in the Q file. This is useful in production builds to avoid duplicate camera names. -nolights Causes the exporter not to create any lights in the Q file. This is useful in production builds to avoid duplicate light names. -notextures Causes the exporter to not include diffuse or specular maps in the exported Q file. <Maya file> The fully qualified file name of the Maya file to be exported. This will not normally be specified if using Batch processing, however if it is, then it will be the last file to be processed.
For each exported Maya file, a QServer q file will be created. The name of the q file will be the same as the root name of the Maya file with .q appended unless an output filename is specified with "-o". For example if the Maya file name is myMayaFile.ma this will export to myMayaFile.q
By default any messages that are generated when exporting go to stdout or stderr. This is normally displayed in the window that the command is executing in. Using the standard re-directors these messages can be re-directed to a file that can then be viewed in a text editor. This is especially useful when doing a batch export.
To do this append '>myStdOut.txt 2>myStdErr.txt' to the command line. For example if you are exporting myMayaFile.ma using Maya3 and you want the normal output to go to std.txt and the error output to go to err.txt, then the command line would be
maya3ToQ -v -b class.q myMayaFile.ma >std.txt 2>err.txt
Every message has some header information, the actual content of this depends on the level of 'verbosity' for the logger which is set by the installation process (this is not the -v option described above). At the bare minimum this will be the 'message type', and 'system' that issued the message. The type will be one of 'info', 'warning', 'error', 'debug'. You will not be likely to see 'debug' messages unless you have a debug release of the software. 'error' messages denote a failure in the export. 'warning' messages may be a failure , or may just indicate that the exporter was uneasy about something that it found. 'info' messages tell you what the exporter did. They may or may not be important to you, but you will surely need them when something unexpected happens. a typical set of informational message is shown below:
info|exporter|Trying specular map texture name 'e:/Qube/Mouser/mouser_s.jpg'
info|exporter|Created shader 'mouser01a_clothes'
info|exporter|shininess -> 10.000000
info|exporter|ambient ->
info|exporter|0.016520 0.016520 0.016520
info|exporter|diffuse ->
info|exporter|12652047124.125000|0|1.000000 1.000000 1.000000
info|exporter|specular ->
info|exporter|0.500000 0.500000 0.500000
info|exporter|emissive ->
info|exporter|0.000000 0.000000 0.000000
info|exporter|Exporting weights with a joint limit of 4
info|exporter|Joint Histogram ...
info|exporter|Max joints per vertex = 4
info|exporter|Num vertices = 660
info|exporter|Num joints = 50
info|exporter|0 vertexes have -> 0 joint influences
info|exporter|641 vertexes have -> 1 joint influences
info|exporter|19 vertexes have -> 2 joint influences
info|exporter|0 vertexes have -> 3 joint influences
info|exporter|0 vertexes have -> 4 joint influences
The exporter uses the Maya© libraries therefore you must ensure that you have the correct exporter and a fully licensed version of Maya©.
Supported versions and features are listed here.
Some features are common to all Q exporters and are therefore documented here.
For the full information on texture support see here
mayaToQ converts one or more Maya files containing polygon meshes, skins, hierarchies and animations to Q database format file (.q). The mayaToQ utility can convert both '.mb' (Maya binary) and '.ma' (Maya ASCII) files.
The exporter searches for the base Q file in the following order until a valid file is found:
Specify a filename using the "-b" command line option. We suggest that you use this option only if you want to over-ride the system configuration.
In the windows registry
The produced hierarchy is exported to a default zone named "tempZone". The output of mayaToQ can therefore be viewed using the command
qview -z tempZone myMayaFile.q or more simply qview myMayaFile.q
Character skins are attached to a skeleton of joints during export if they conform to the following naming convention. A character skeleton is built as a joint hierarchy with the top node known as the "heart".
The heart node which is usually a locator for a character model is named as follows:
<aName>heart
Where:
'aName' is unique and is usually the name of the character
'heart' is in lower case and is mandatory
In Maya, skins must be created separately and not linked into the hierarchy. However, since a skin is only valid in the Q database if it is parented directly to a heart, the exporter has to determine which heart to parent it to. It does this using a naming convention for the skin. The convention is that all skin names must begin with the heart name. For LOD (Levels Of Detail) skins see skin LOD naming for the full naming convention. See below for the single skin naming convention.
Single skin names must be:
<heartName><anyName>
Where:
'heartName' is the name of the heart
'anyName' can be any unique identifier.
For example, assume that a character named "foo" has the top locator node (heart) named "fooheart". A single skin that is to be used as the body of this character would probably be named "fooheartbody" and must not be linked into the hierarchy. The corresponding Bones or Joints on the other hand must be linked under the heart node.
Therefore it follows that for a skin to be bound to a joint hierarchy and exported, a heart node must be present in the hierarchy. If a skin does not conform to the naming convention, or the heart node is not present in the hierarchy, then an Error message is generated.
When choosing names for the scene, you must not use the following reserved names.
"end", "lodinfo", "visible", "collider", "collidee", "intersectable",
"defbbox", "exportinfo", "markup", "framesample", "epsrotation",
"epsposition", "epsscale", "epsquality", "makeCluster", "heartSeparate"
The exported QServer objects often require extra parameter information that is not authored in Maya. To do this, parameters are entered into a special text file called the 'Heart Text File'. The exporter then reads this file and extracts (parses) the required parameters. The actual parameters are described in the relevant sections below. Error messages will result if required parameters are not present or are in the wrong format.
The text file must either be located in the same directory as the Maya file that is being exported or in the current directory. The name of the text file must be as follows:
<heartName>.txt
or <mayaname>.txt (deprecated form)
Where:
'heartName' is the name of the heart
for the animated character
'mayaName' is the name of the Maya file without the extension.
This form is deprecated and should not be
used
For example if exporting the character "foo" with heart name "fooheart" from the file "mayafoo.ma". Then the Heart Text File must be named "fooheart.txt".
Any line in the text file where the first non blank character is a '#', is treated as a comment and ignored by the exporter. Blank lines are also ignored by the exporter. In general, spaces before, around and at the end of the parameters/seperators in a line are also ignored. The text file can be generated using a text editor such as 'Notepad'. If you use a more sophisticated editor, make sure it is saved in plain text format by using the 'save as' option.
For a general introduction to the sampling process see here.
By default, animations (position, rotation and scale) are sampled using the original key frames. In most cases this will result in an accurate reproduction of the animation in the QServer engine. However some animations may require more precise sampling and this can be achieved by sampling every frame between the start key frame and the end key frame. Although the animation may be more accurate, you will need to balance this against an increased rendering overhead which may adversely effect the final result. There are two methods for controlling the sampling method.
The format of the 'framesample' setting in the Heart File is:
<framesample> <sep> <value>
Where:
framesample Is mandatory and case insensitive
sep Is the separator and is either '=' or ':'
value Is 'true' or '1' to turn on frame sampling
or
Is 'false' or '0' to turn off frame sampling and revert to the default 'key frame' sampling mode.
After the samples have been gathered they are 'culled'. The decision to keep or discard a sample is controlled by the 'Epsilons' for the position, rotation or scale transforms. There are five settings that control these values
<epsquality><sep><value>
Where:
epsquality Is mandatory and case insensitive. This indicates that a preset quality for the position, rotation and scale settings follow. sep
Is the separator and is either '=' or ':' value This is an integer from '1' the coarsest Epsilons to '5' the finest Epsilons. The default setting is '3'
The next three settings in the Heart Text File set the individual Epsilons.
<epsposition><sep><value>
<epsrotation><sep><value>
<epsscale><sep><value>
epsposition
epsrotation
epsscale
Are mandatory and case insensitive. They indicate which Epsilon is to be set sep
Is the separator and is either '=' or ':' value Is a positive decimal value. This will normally be less than 0.01, and greater than 0.0000001
The Epsilons that have been used are listed in the standard output messages
Animation segmentation data format is described here. It should be placed in the heart text file.
To play a QAM (Q Animation Machine) file on a character in QStudio or the QAM test utilities you need to define markups in the heart text file as shown here.
polygonal hierarchies and instancing
smooth skinning and binding
animation
all IK solvers
texture support
phong materials, supporting
Color file render node for texture.
Transparency color, not render node. No transparency maps.
Ambient color, not render node. No ambient maps.
Incandescence color, not render node. No incandescence maps.
Multiple Levels of Detail can be defined for a mesh or a skin (they do not use the Maya Level of Detail facility). For an overview look here. The transitioning of the LOD must be defined in the Heart text file.
Levels of detail are authored separately and generally occupy the same space. Their names must conform to the following formats
A skin can be authored as multiple levels of detail. Each skin must be bound to the same set of bones, and usually occupies the same physical space. A single skin is differentiated from a set of LOD skins by a naming convention. Like a single skin, the LOD skins must not be linked into the Maya hierarchy.
A LOD skin name (the transform name in the Maya Attribute Editor) must be as follows:
<heartName><anyId>skin_lod<n>
Where:
'heartName' is the name of the heart
for the character or model.
'anyId' is an identifier to uniquely differentiate multiple skin LOD's in a model. If there is only one Skin LOD then it is optional.
'skin_lod' is in lower case and is mandatory.
'n' represents the level of detail number and is mandatory. '1' is the highest level of detail, '2' the next lowest level of detail and so on down. Up to nine levels of detail can be defined.
The name combination '<heartName><anyId>skin' is used to uniquely identify the LOD set for the transitioning settings
For example if the heart name is 'fooheart' and our unique ID is 'Body' then the second level LOD skin will be named:
fooheartBodyskin_lod2
and the LOD set identifier will be:
fooheartBodyskin
Make sure that the corresponding Maya generated mesh name is of the form:
<heartName><anyId>skin_lodShape<n> OR <heartName><anyId>skin_lod<n>Shape
Check that this is the case by using the Maya Attribute Editor and change the name accordingly. From the above example this should be:
fooheartBodyskin_lodShape2 or fooheartBodyskin_lod2Shape
The individual LOD skins must not be linked into the Maya
hierarchy, the exporter will bind the skin to the model
through the modelName heart.
The joints and the total number of joints for each skin LOD must be the same as the top level LOD skin.
When the LOD is exported a 'Q' SkinInstance and LODHolder object is created, and the LOD skins are parented to the LodHolder object. The name of the SkinInstance and LODHolder is generated from the lod skin names as follows:
<LOD set identifier>LOD
For example for the model "foo" if the following Maya skins are created:
fooheartMyIdskin_lod1
fooheartMyIdskin_lod2
fooheartMyIdskin_lod3
These will export as:
'Q' SkinInstance name
fooheartMyIdskinLOD 'Q' LODHolder name fooheartMyIdskinLOD
'Q' LOD names fooheartMyIdskin_lod1
fooheartMyIdskin_lod2
fooheartMyIdskin_lod3
A mesh can be authored as multiple levels of detail. Each mesh usually occupies the same physical space. A single mesh is differentiated from a set of LOD mesh's by a naming convention.
A LOD mesh name (the transform name in the Maya Attribute Editor) must be as follows:
<aModelName><anyId>mesh_lod<n>
Where:
aModelName Is the name of the character or model
anyId Is an identifier to uniquely differentiate multiple mesh LOD's in a model. If there is only one mesh LOD then it is optional.
mesh_lod Is in lower case and is mandatory
n Represents the level of detail number and is mandatory. '1' is the highest level of detail, '2' the next lowest level of detail and so on down. Up to nine levels of detail can be defined
The name combination '<aModelName><anyId>mesh' is used to uniquely identify the LOD set for the transitioning settings
For example if the model is 'foo' and our unique ID is 'Body' then the first level LOD skin will be named:
fooBodymesh_lod1
and the LOD set identifier will be:
fooBodymesh
Make sure that the corresponding Maya generated mesh name is of the form:
<aModelName><anyId>mesh_lodShape<n> or <aModelName><anyId>mesh_lod<n>Shape
Check that this is the case by using the Maya Attribute Editor and change the name accordingly. From the above example this should be:
fooBodymesh_lodShape1 or fooBodymesh_lod1Shape
The individual LOD meshes must be linked into the Maya model
hierarchy.
When the LOD is exported a 'Q' LODHolder object is created, and the LOD meshes are parented to this object. The name of the LODHolder is generated from the LOD mesh names as follows:
<LOD set identifier>LOD
For example for the model "foo" if the following Maya meshes are created:
fooMyIdmesh_lod1
fooMyIdmesh_lod2
fooMyIdmesh_lod3
These will export as:
'Q' LODHolder name fooMyIdmeshLOD
'Q' LOD names fooMyIdmesh_lod1
fooMyIdmesh_lod2
fooMyIdmesh_lod3
The transitioning settings of the LOD's are defined in the Heart Text file for the model. The format of the setting is
lodinfo<sep><LODid><D><sp><T>
Where:
| lodinfo | is case case insensitive | |
| LODid | is the unique LOD set identifier for the skin or mesh | |
| sep | is one or more separator spaces or an '=' or an ':' | |
| D | see here. | |
| T | see here. |
For example for the LOD set identifier 'fooheartMyIdskin' , if the first LOD transition is to occur at 20.5 meters in a time of 0.1 seconds, the LOD transition setting in the Heart Text file will be:
lodinfo fooheartMyIdskin 20.5 0.1
Collision boxes are special meshes whose name conforms to the following:
Either:
collideboxShape<n>
or:
collideboxShape0<n>
Where 'n' is a number between 0 and 20 inclusive
or:
collidebox_<anyName>
When the exporter encounters a collision box object it calculates the size of the smallest bounding box and exports this as a Q Region. The default flag settings for the collision box are:
visible = 0, collidee = 1, collider = 1, intersectable = 1
These settings can be over-ridden in the Heart Text file as shown below
A default collision box that surrounds the whole scene is automatically constructed unless the following line is found in the Heart Text file:
To turn off the default collision box creation:
defbbox = 0 or false
To turn on the default collision box creation (i.e. the default ):
defbbox = 1 or true
The flag settings for the default collision box are:
visible = 0, collidee = 1, collider = 1, intersectable = 1
These flag settings can be over-ridden in the Heart Text file as shown below
The name of the default collision box is :
<heartname>_collidebox
In addition to the LOD transition parameters there are other flag settings that can be made for a mesh, skin and collision boxes using the Heart Text file . These settings influence the visibility and properties of the mesh, and have the following syntax:
exportinfo<sep><name>
visible = <0> or <1>
lightable = <0> or <1>
collider = <0> or <1>
collidee =<0> or <1>
intersectable = <0> or <1>
Where "exportinfo" is case insensitive, 'sep' is the separator and can be one or more spaces, '=' or ':' . The "name" is the object name. This line is then immediately followed by one or more of the settings on separate adjacent lines. The settings can be interspersed with comment lines.
For example if you wanted to reverse some of the settings of the default collision box then the following entries will do that:
#this is a comment line
#the next lines reverse the default visible and collidee flag settings for the default collision box
# note that the character case is optional
EXPORTinfo = defbbox
visible = 1
#A comment in between setting lines is OK, but not a blank line
collidee = 0
If exportinfo is not specified then the default settings are as follows
For skins and meshes:
visible = 1, collider = 0, collidee = 0, intersectable = 0
For Collision boxes:
visible = 0, collider = 1, collidee = 1, intersectable = 1
For specific details regarding specular shading, see below.
Texture files for both diffuse and specular maps can be used in either mip-built or non-mip-built form. Mip-building allows the different resolutions of the texture to be individually authored for better quality. By offering lower mip-levels, you also benefit from the texture streaming behavior of the QPlayer: only a defined lowest mip-level of a texture (normally 64x64) needs to be downloaded in the initial load of a scene over the internet. Higher mip-levels are downloaded in the background resulting in an image being displayed to the user more quickly.
If mip-built textures are to be used, the map files for the diffuse and specular maps must not be named 'name_number.type', as this naming is reserved for the individually built levels output by mipBuilder.
If mip-built textures are not to be used, the file type must be a supported image format. If mip-built textures are to be used, any image file type supported by Image Magick© will be converted to the Q-supported file types automatically.
All textures, regardless of whether they will be mip-built, or not, must be square, and the size must be a power of 2.
The diffuse channel of a Q shader can have both a color and a map. The maya channel equivalent only directly supports one or other. The supported ways of setting up the Maya shader are:
The alpha channel in the diffuse color is set by altering the "transparency" channel in the maya shader. The maya channel supports red, green and blue, but the Q shader only supports a single floating-point value for alpha. The exporter therefore uses the red channel of the maya object.
Similar restrictions to the diffuse shading color apply to the specular. The exporter supports the following:
While exporting you may receive the following warning message:
Bogus shading groups on 'meshname' - reset materials
this message is indicating that a polygon for that mesh is included in more than one shading group. Check the shaders for the surface and re-export.
|
|||
|
|
Qube Software Limited © 2000-2004
|
|