Command-Line Interface

You need a Studio license to use this feature. It is included in v1.1.0 and higher.

This feature is currently under development. Please report any issue to transmutr@lindale.io

General usage

The CLI (short for Command-Line Interface) is a very powerful tool that allows users to easily process large sets of models. To use the CLI, first open a terminal and type the path to the location where Transmutr.exe is stored.

If you installed Transmutr per user (the "Only for me" option in the installer) then it should be located at:

C:/Users/YourUsername/AppData/Local/Programs/Transmutr/

If you installed Transmutr per machine (the "Anyone who uses this computer" option in the installer) then it should be located at:

C:/Program Files/Transmutr/

To simply convert a model, add the convert command followed by the path to the model. This will convert your model to a Sketchup file with the same name, right in the current directory. Please note that the path to transmutr.exe will slightly differ on your system.

C:/Users/Frodo/AppData/Local/Programs/Transmutr/transmutr.exe convert C:/models/tree.obj

Typing the complete path to Transmutr's location is quite verbose. If you prefer to avoid this, you can add the Transmutr's folder to your environment's PATH variable, like in this guide.

In this way, your computer knows where to look for when you only type transmutr.exe instead of the whole path. We use this method in the rest of this documentation to keep things short.

You can specify additional options by adding parameters right betweenconvert and the model's path. For instance, add the --output parameters to specify the destination and the name of the converted model:

transmutr.exe convert --output C:/sketchup/my_converted_tree.skp C:/models/tree.obj

You have control over the same set of settings as in Transmutr's graphical interface. For example, to generate a Sketchup model scaled down by half, with 95% of its geometry simplified, you could type:

transmutr.exe convert --scale 0.5 --simplification 0.95 C:/models/tree.obj

To list all the available parameters, type transmutr.exe convert --help. Please note that some parameters have a shorthand version that you can use to avoid typing long keywords, such as -o instead of --output.

> Transmutr.exe convert --help
Transmutr's Command-Line Interface
Positionals:
input Paths to the models to convert, can contain globbing patterns [array] [required] [default: []]
Options:
--version Show version number [boolean]
--output, -o Output path, must be a directory when converting multiple models [string]
--preset, -p Path to a preset configuration to load [string]
--scale Scale multiplier [number]
--sourceUnit, --su Unit of the input model [choices: "m", "cm", "mm", "f", "i"]
--up Up-axis of the input model [choices: "x", "y", "z", "nx", "ny", "nz"]
--origin New origin of the output model [choices: "default", "center", "bottomCenter", "topCenter"]
--simplification, -s Simplification level of the output model, in the [0,1] range [number]
--simplificationPreserveNormals, --snorm Simplification will try to preserve the face normals [boolean]
--simplificationPreserveUV, --suv Simplification will try to preserve the texture coordinates [boolean]
--smoothCoplanar, --smc Smooth the coplanar faces [boolean]
--proxyEnscape, --pxen Create an Enscape proxy, the high-resolution skp model will be generated alongside the output model [boolean]
--proxyThea, --pxth Create a Thea proxy, the high-resolution mesh.thea model will be generated alongside the output model [boolean]
--proxyVray, --pxvr Create a V-Ray proxy, the high-resolution vrmesh model will be generated alongside the output model [boolean]
--proxyPreview, --pxprev Type of proxy preview [choices: "billboardcross", "billboardfaceme", "boundingboxfaces", "boundingboxwireframe", "simplifiedgeometry", "skpfile"]
--proxyPreviewBillboardFilePath, --prprevbill Path to the image file to use as a billboard [string]
--proxyPreviewSkpFilePath, --pxprevskp Path to the SketchUp file to use as a proxy preview [string]
--proxyPreviewSkpFileFaceMe, --pxprevfaceme Makes the proxy preview SketchUp file always faces the camera (billboard) [boolean]
--help Show help [boolean]
Examples:
transmutr.exe convert house.dae
transmutr.exe convert --simplification 0.25 statue.fbx
transmutr.exe convert --output C:/sketchup/mytree.skp tree.fbx
transmutr.exe convert --scale 5 --origin bottomCenter models/cornell.obj
Copyright Lindalë 2019

You'll notice that executing transmutr.exe without command actually opens the classical Transmutr graphical interface, which can also be useful.

Convert multiple models

To convert several models in one go, you can type their names one after another:

transmutr.exe convert C:/models/tree.fbx C:/models/sofa.obj C:/models/lamp.3ds

When converting multiple models, the options that you specify apply to all the models.

Please note that options must still be placed right after the convert command and before the paths to the models.

The CLI accepts globbing patterns that provide more flexibility when selecting models. For instance, * is useful to select several files without writing their complete names. Thus, the following command converts all the models in C:/models/trees/ that end with .obj:

transmutr.exe convert C:/models/trees/*.obj

Likewise, ** can help you search for models in several directories. For example, the following command converts all the models named tree.fbx located in any directory under C:/models/:

transmutr.exe convert C:/models/**/tree.fbx

Range operators are also useful to select names with some variations in them. The following command converts any model which name matches tree1.obj, tree2.obj, up to tree9.obj:

transmutr.exe convert C:/models/tree[1-9].obj

Similarly, we can select a range of letters. In this example, we convert any file with a name that matches furniture_a.obj, furniture_b.obj, ..., up to furniture_z.obj:

transmutr.exe convert C:/models/furniture_[a-z].obj

You can also combine different patterns by wrapping them in parentheses, separated by |, following one of the @, +, *, +, or ! operators:

  • @ matches exactly one occurrence of the patterns

  • ? matches zero or one occurrence

  • * matches zero or more occurrences

  • + matches one or more occurrences

  • ! matches anything that does not match the patterns

For example, the following command converts any file that ends either with the .obj or .fbx extensions:

transmutr.exe convert C:/models/*.@(obj|fbx)

In this other example, we convert any model which name matches treeX.obj where X can be any number with one or more digits:

transmutr.exe convert C:/models/tree+([1-9]).obj

Finally, it's possible to combine different patterns to carry out very specific searches:

transmutr.exe convert C:/models/**/tree_collection_[1-5]/*_highpoly.@(fbx|obj)

Using the CLI for scripting

One way in which the CLI can be even more powerful is by including it in a scripting pipeline that automates tasks that would be tedious and time-consuming to perform manually.

This section contains examples that show how such tasks can be handled by combining Transmutr with your own scripts.

Ruby example: generating a library of LODs

In some contexts, it is useful to have several LODs (Level Of Detail) of the same model: for instance a high-resolution model for close-up shots, a medium-resolution model for mid-range shots and a very low-resolution model for distant shots. In this way, we can save performance without degrading visual quality.

In this example, we use a script written in the Ruby programming language to convert hundreds of models to three different LODs each and to sort them in appropriate output folders, all in a few lines of code.

Doing this manually would be a grueling and time-consuming job that could take several hours. Thanks to the CLI, it's now a matter of minutes.

# Each model will be exported with 3 levels of detail
# - Original quality
# - Slight simplification (75% triangles)
# - Heavy simplification (1% triangles)
qualities = [1, 0.75, 0.01]
# Convert the models
for quality in qualities
# We group models in different folders depending on their simplification level
# -> Root folder
# |-> output
# |-> quality_100
# |-> quality_75
# |-> quality_1
outputPath = "output/quality_#{(quality * 100).round}/"
# Generate the command for this specific level of details
command = "C:/Users/Merwan/AppData/Local/Programs/Transmutr/Transmutr.exe convert --simplification #{quality} --output #{outputPath} models/*.obj"
# Run the command
process_id = Process.spawn(command)
# Wait for the command to be finished and check if an error occurred (exit code != 0)
process_status = Process.wait2 process_id
if process_status[1] != 0
print "Something wrong happened!"
end
end

Sketchup actually supports Ruby scripting, which means that you can run such scripts directly from Sketchup if you wish to. To do so, check out the Ruby console documentation.

.bat example: generating watermarked billboard proxies

Coming soon!