Dmxedit

Dmxedit is a command-line SDK tool which manipulates DMX model files. It focuses on flex animation.

Usage

dmxedit [ -h | -help ] [ -game <$game> ] [ -nop4 ] [ -set $var=val ] [ script.lua ]

-h

prints help information, including a list of available functions.

-game

Sets the VPROJECT environment variable to the specified game.

-nop4

Disables Perforce integration.

-set

Sets the lua variable var to the specified val before the script is run.

Lua

Unusually, commands are issued to dmxedit by creating Lua scripts. Script load DMX files, make changes to them, then save them to a location (possibly the original location).

Here is a simple script to create wrinkle maps:

Load("C:/heavy_morphs_high.dmx")

SetWrinkleScale("BrowInV", "WrinkleNose", -0.5)
SetWrinkleScale("BrowInV", "RaiseBrowIn", 2)

ComputeWrinkles()

Save("C:/heavy_morphs_high.dmx")

Valve's dmxedit scripts are available at SourceFilmmaker\game\sdktools\lua\. These can be used to set up your model in the same way as Valve's.

Load/Save

Load( < $file.dmx | $file.obj >, [ $loadType ] )

Replaces the current scene with the specified scene. The current mesh will be set to the first mesh with a combination operator found in the new scene. $loadType is one of "absolute" or "relative". If not specified, "absolute" is assumed.

Save( [ $file.dmx | $file.obj ], [ $saveType ], [ $delta ] )

Saves the current scene to either a single dmx file or a sequence of obj files. If $file is not specified, the filename used in the last Load() command will be used to save the file. $saveType is one of "absolute" or "relative". If not specified, "absolute" is assumed. If $delta is passed and the save type is OBJ, then only a single OBJ of that delta is saved. "base" is the base state.

Import( < $file.dmx >, [ $parentBone ] )

Imports the specified DMX model into the scene. The imported model can optionally be parented (which implictly skins it) to a specified bone in the existing scene via $parentBone.

Merge( < $src.dmx >, < $dst.dmx > )

Merges the current mesh onto the specified dmx file and saves to the second specified dmx file

MergeMeshAndSkeleton( < $src.dmx >, < $dst.dmx > )

Merges the current mesh onto the specified dmx file and saves to the second specified dmx file. This function also merges deltas.

FileExists( < $filename > )

Returns true if the given filename exists on disk, false otherwise

Utility

SetDistanceType( < $distanceType > )

Sets the way distances will be interpreted after the command. $distanceType is one of "absolute" or "relative". By default distances are "absolute". All functions that work with distances (Add, Interp and Translate) work on the currently selected vertices. "absolute" means use the distance as that number of units, "relative" means use the distance as a scale of the radius of the bounding sphere of the selected vertices.

Delta states

Add( < $delta >, [ #weight ], [ #featherDistance ], < $falloffType > )

Adds specified state to the current state of the mesh weighted and feathered by the specified #weight, #featherDistance & $falloffType. $falloffType is one of "straight", "spike", "dome", "bell". Note that only the specified delta is added. i.e. If Add( "A_B" ); is called then just A_B is added, A & B are not. See AddCorrected();

AddCorrected( < $delta >, [ #weight ], [ #featherDistance ], < $falloffType > )

Same as Add() except that the corrected delta is added. i.e. If AddCorrected( "A_B" ); is called then A, B & A_B are all added. This works similarly to SetState() whereas Add() just adds the named delta.

DeleteDelta( < $delta > )

Deletes the named delta state from the current mesh

DeltaCount( )

Returns the number of deltas in the current mesh

DeltaName( < #deltaIndex > )

Returns the name of the delta at the specified index. Use DeltaCount() to get a count of how many deltas are present

DeltaRadius( < $delta > )

Returns the radius of the specified delta, if it exists. Radius of a delta is defined as the radius of the tight bounding sphere containing all of the deltas added to their base state values

Interp( < $delta >, [ #weight ], [ #featherDistance ], < $falloffType > )

Interpolates the current state of the mesh towards the specified state, $weight, #featherDistance and $falloffType. $falloffType is one of "straight", "spike", "dome", "bell"

ListDeltas( )

Prints a list of all of the deltas present in the current mesh

MaxDeltaDistance( < $delta > )

Returns the maximum distance any vertex moves in the specified delta. Returns 0 if the delta specified doesn't exist

ResetState( )

Resets the current mesh back to the default base state, i.e. no deltas active

SaveDelta( < $delta > )

Saves the current state of the mesh to the named delta state

SetState( < $delta > )

Sets the current mesh to the specified $delta

Wrinkle maps

See also Wrinkle maps.

ComputeWrinkle( < $delta > [ , #scale = 1 [ , $operation ] ] )

Updates the wrinkle stretch/compress data for the specified delta based on the position deltas for the current state scaled by the scale value. If $operation isn't specified then "REPLACE" is assumed. $operation is one of: "REPLACE", "ADD". Note that Negative (-) values enable the compress map and Positive (+) values enable the stretch map. This also sets the wrinkle scale to 1

ComputeWrinkles( [ #bOverwrite = false ] )

Uses the current combo rules ( i.e. The wrinkleScales, via SetWrinkleScale()) to compute wrinkle delta values. If #bOverwrite is false, only wrinkle data that doesn't currently exist on the mesh will be computed. If #bOverwrite is true then all wrinkle data will be computed from the combo rules wiping out any existing data computed using ComputeWrinkle().

SetWrinkleScale( < $controlName >, < $rawControlName >, < #scale > )

Sets the wrinkle scale of the raw control of the specified control. NOTE: SetWrinkleScale merely sets the wrinkle scale value of the specified delta on the combination operator. This value is only used if ComputeWrinkles() is called after all SetWrinkleScale() calls are made. A wrinkle scale of 0 means there will be no wrinkle deltas. The function to compute a single delta's wrinkle values, ComputeWrinkle() does not use the wrinkle scale value at all. Negative (-) is compress, Positive (+) is stretch.

Flex controllers

AddDominationRule( { < $dominator > [ , ... ] }, { < $supressed > [ , ... ] } )

Create a domination rule. A lua array of strings is passed as the 1st argument which are the controls which are the dominators and a lua array of strings is passed as the 2nd argument which are the controls to be supressed by the dominators.e.g. AddDominationRule( { "foo" }, { "bar", "bob" } );

GroupControls( < $groupName > [ , $rawControlName ... ] )

Groups the specified raw controls under a common group control. If the group control already exists, the raw controls are added to it

ImportComboRules( < $rules.dmx >, [ #bOverwrite ], [ #bPurgeDeltas ] )

Imports the combintion rules from the specified dmx file and replaces the current rules with those from the file is #bOverwrite specified or is true. If #bOverwrite is false then any existing controls that are not in the imported rules file are preserved. If #bPurgeDeltas is specified and is true, then any delta states which are no longer referred to by any combination rule or control will be purged.

ReorderControls( < $controlName [ , ... ] > )

Reorders the controls in the specified order. The specified controls will be moved to the front of the list of controls. Not all of the controls need to be specified. Unspecified controls will be left in the order they already are after the specified controls

SetEyelidControl( < $controlName > [ , < true | false > ] )

Sets the specified morph control to be an eyelid control if the 2nd argument is true.If the 2nd argument is omitted, true is assumed

SetStereoControl( < $controlName > [ , < true | false > ] )

Sets the specified morph control to be stereo if the 2nd argument is true.If the 2nd argument is omitted, true is assumed

Expression presets

CachePreset( < $preset.pre >, [ $expression.txt ] )

Caches the specified $preset file for later processing by a call to CreateDeltasFromCachedPresets(). If an $expression.txt file pathname is specified, an expression file will be written out for this preset file

ClearPresetCache( )

Removes all preset filenames that have been specified via CachePreset() calls

CreateDeltasFromCachedPresets( [ #bPurgeExisting = true ], [ { "NoPurge1", ... } ] )

Creates a new delta state for every preset defined in the preset files specified by previous CachePreset() calls. Calling this calls ClearPresetCache(). #bPurgeExisting specifies whether existing controls should be purged. If #bPurgeExisting is true, then an optional array of deltas to not purge can be specified.

CreateDeltasFromPresets( < $preset.pre >, [ #bPurgeExisting = true ], [ { "NoPurge1", ... } ], [ $expression.txt ] )

Creates a new delta state for every present defined in the specified preset file. #bPurgeExisting specifies whether existing controls should be purged. If #bPurgeExisting is true, then an optional array of deltas to not purge can be specified.

CreateExpressionFileFromPresets( < $preset.pre >, < $expression.txt > )

Creates a faceposer expression.txt and expression.vfe file for the specified preset file

CreateExpressionFilesFromCachedPresets( )

Creates a faceposer expression.txt and expression.vfe file for each of the preset/expression file pairs specified by previous CachePreset calls

Meshes

Mirror( [ $axis ] )

Mirrors the mesh in the specified axis. $axis is one of "x", "y", "z". If $axis is not specified, "x" is assumed (i.e. "x" == mirror across YZ plane)

RemapMaterial( < #index | $srcMaterial >, < $dstMaterial > )

Remaps the specified material to the new material, material can be specified by index or name

RemoveFacesWithMaterial( < $material > )

Removes faces from the current mesh which have the specified material

RemoveFacesWithMoreThanNVerts( < #vertexCount > )

Removes faces from the current mesh which have more than the specified number of faces

Vertices

Select( < $delta >, [ $type ] )

Changes the selection based on the vertices present in the specified $delta. $type is one of "add", "subtract", "toggle", "intersect", "replace". If $type is not specified, "add" is assumed.

SelectHalf( < $halfType > )

Selects all the vertices in half the mesh. $halfType is one of left or right. Left means the X value of the position is >= 0, right means that the X value of the position is <= 0. So it's the character's left (assuming they're staring down -z)

SelectionRadius( )

Returns the radius of the currently selected vertices, if nothing is selected, returns 0. Radius of a the vertices defined as the radius of the tight bounding sphere containing all of the vertices.

GrowSelection( < #size > )

Grows the current selection by the specified $size

ShrinkSelection( < #size > )

Shrinks the current selection by the specified $size (integer)

Translate( < #xTranslate, #yTranslate, #zTranslate >, [ #falloffDistance, $falloffType ] )

Translates the selected vertices of the mesh by the specified amount

Rotate( < #xRotate, #yRotate, #zRotate >, [ #xOffset, #yOffset, #zOffset ], [ #falloffDistance, $falloffType ] )

Rotates the current selection around the center of the selection by the specified Euler angles (in degrees). The optional offset is added to the computed pivot point.

Scale( < #xScale >, [ #yScale, #zScale ] )

Scales the position values by the specified amount. If only 1 scale value is supplied a uniform scale in all three dimensions is applied

ComputeNormals( )

Computes new smooth normals for the current mesh and all of its delta states.