# 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`** ![](/files/-LmtWRiff1kKRHljIiqw) {% 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.transmutr.com/manual/command-line-interface.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.