# Command-Line Interface {% hint style="success" %} You need a **Studio** license to use this feature. It is included in Transmutr v1.1.0 and higher. {% endhint %} {% hint style="warning" %} This feature is currently under development. Please report any issue to {% endhint %} ## 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. {% hint style="info" %} 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/`** {% endhint %} 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`** ![](https://1807576756-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbleSCzt45l7QT5OXk4%2F-LmtWLKXCXuD3KGuU6Dl%2F-LmtWRiff1kKRHljIiqw%2Ftransmutr_cli.png?alt=media\&token=3e312a46-84b7-41cb-b18f-7722738a241c) {% hint style="info" %} 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](https://www.computerhope.com/issues/ch000549.htm). 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. {% endhint %} You can specify additional options by adding parameters right between**`convert`** 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] --copyMaps, --cpm Copy texture maps to the output folder [boolean] --absolutePaths, --absp Writes asset paths (material maps, proxies) as absolute [boolean] --relativePathsPrefix, --relpfx Adds a custom prefix to relative paths [string] --prefixMaterials, --pfxmtl Adds the model name to the material names [boolean] --maxMeshScaleCorrection, --maxsc Maximum scale factor when scaling meshes to avoid the tiny faces issue [number] --meshScaleCorrectionMultiplier, --scmult Multiplier for the scale factor, in case it is too strong or not enough [number] --ply2vrmeshPath, --ply2vr Writes asset paths (material maps, proxies) as absolute [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] --proxyPlaceholder, --pxplhdr Type of proxy placeholder [choices: "billboardcross", "billboardfaceme", "boundingboxfaces", "boundingboxwireframe", "simplifiedgeometry", "skpfile"] --proxyPlaceholderBillboardFilePath, --pxplhdrbill Path to the image file to use as a billboard [string] --proxyPlaceholderSkpFilePath, --pxplhdrskp Path to the SketchUp file to use as a proxy preview [string] --proxyPlaceholderSkpFileFaceMe, --pxplhdrfaceme 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 ``` {% hint style="info" %} You'll notice that executing **`transmutr.exe`** without command actually opens the classical Transmutr graphical interface, which can also be useful. {% endhint %} ## 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`** {% hint style="info" %} 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. {% endhint %} The CLI accepts globbing patterns to 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)`** {% hint style="warning" %} Note that the paths and patterns are case-sensitive. So a pattern containing `.fbx` will not match a filename ending with `.FBX` . {% endhint %} ## 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](https://www.ruby-lang.org) 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 would take several hours. Thanks to the CLI, it is now a matter of minutes. ```ruby # 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 = "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 ``` {% hint style="info" %} Sketchup actually [supports Ruby scripting](https://developer.sketchup.com/en/content/welcome), which means that you can run such scripts directly from Sketchup if you wish to. To do so, check out the [Ruby console documentation](https://developer.sketchup.com/en/content/ruby-sketchup). {% endhint %} ### .bat example: generating watermarked billboard proxies {% hint style="warning" %} Coming soon! {% endhint %}