This page illustrates all commands and options available for RapidCompact CLI. Commands are executed as pipeline, starting with the first, leftmost command and then continuing with execution of subsequent commands.

In case you want to load and work with multiple 3D assets on the command line, it is important to know about the asset stack implemented in RapidCompact CLI. In fact, by using the -i command, a 3D asset is loaded and pushed to this stack, becoming the stack's top element. If you load a second 3D asset (using -i again), that one will become the new top element of the stack. Subsequent operations will then be applied on this asset, unless it is removed again, using the --pop command. Some commands also need two 3D assets on the stack to operate, such as --bake (short: -b), which bakes texture maps and attaches them to one asset (top of the stack), using data from another one (second highest element on stack).

Another two basic commands are --export (short: -e), exporting the topmost asset of the stack to a file, and --print_info (short: -p), printing some basic information about the topmost asset of the stack to the standard output.

Some important commands are covered in-depth by respective tutorials. However, to quickly explore all the available commands of RapidCompact CLI and learn about their functionality, you can simply scroll down this page. Alternatively, you can also directly jump to the features you are interested in by using the following quick links:

 

Commands Overview

back to top

Commands: General

Command (Short)	#Args	Example	Quick Description
help (h)	0	-h	lists all available parameters
import (i)	1	-i foo.obj [...]	imports an asset from a file more
export (e)	1	-i foo.obj [...] -e opt.gltf	exports an asset to a file more
export_web (w)	1	-i foo.obj [...] -w arg	exports to a directory with HTML 3D viewer more
print_info (p)	0	-i foo.obj -p	prints information about the current 3D asset
pop	0	-i foo.obj [...] --pop [...]	removes the current 3D asset from the stack
duplicate	0	-i foo.obj --duplicate [...]	duplicates the current 3D asset on the stack
flatten	4	-i foo.obj --flatten arg [...]	flattens (combining meshes and transformations) the 3D asset at the top of the stack
scale	1	-i foo.obj --scale 100 [...]	scales the current 3D asset on the stack using units relative to the asset
get (g)	1	-g ao:enabled [...]	gets the value of the given setting and prints it
set (s)	2	-s ao:enabled true [...]	sets the setting with the given name to the given value
read_config	1	--read_config decimation_cfg.json [...]	reads and apply the given config file more
write_config	1	--write_config rpd_config.json	writes current settings to the given config file more
write_metrics arg	1	--write_metrics rpd_metrics.json	writes metrics to a file using this ID
write_info	0	--write_info	writes information about the current 3D asset to a JSON file
selfdocument	0	--selfdocument	writes config metadata

Commands: Main Operations

Command (Short)	#Args	Example	Quick Description
compact (c)	0	-i foo.obj -c -e opt.gltf	turns the current asset into a simplified, textured representation more
unwrap (u)	0	-i foo.obj -u -e uvs.obj	segments and unwraps the current asset, creating a UV atlas more
bake_maps (b)	0	-i foo.obj -i foo2.obj -b -e baked.obj	bakes texture maps for the current asset, using data from the previous one more
triangulate	0	-i foo.obj --triangulate -e triangulated.obj	triangulates asset with mixed tri/quad meshes

Commands: Color Assignment

Command (Short)	#Args	Example	Quick Description
set_checker_texture	0	-i foo.obj --set_checker_texture[...]	assigns a checkerboard texture to the current asset

Commands: Mesh Modification

Command (Short)	#Args	Example	Quick Description
decimate (d)	1	-i foo.obj -d v:8000 [...]	decimates 3D geometry to given no./percentage of vertices/faces more
remove_duplicate_vertices	0	-i foo.obj --remove_duplicate_vertices [...]	removes duplicated vertices from the asset
remove_invisible_geometry	0	-i foo.obj --remove_invisible_geometry [...]	removes geometry that cannot be seen from the asset
remove_small_features	1	-i foo.obj --remove_small_features 0.5 [...]	removes lumps of geometry with their longest axis smaller than the given length or percentage of the whole scene's longest axis

Commands: Rendering

Command (Short)	#Args	Example	Quick Description
set_view_matrix (v)	1	-i foo.obj -v "1 0 0 0 0 1 0 0 0 0 1 -23" [...]	uses a given 3x4 view matrix (instead of computing one) more
render_image	1	-i foo.obj --render_image [...]	renders an image of the current asset to a file more
render_turntable	2	-i foo.obj --render_turntable img 32 [...]	renders a turntable-like image series to a directory more

 

Importing and Exporting Meshes

back to top

To import an asset into the application, use the command --import (short: -i). The currently supported formats for import are:

Import Format	Remarks
glTF	.glb and .gltf
VRM	VRM input data required; more info about VRM format here
USD/USDZ	.usd, .usda, .usdc, .usdz; Supported Materials: Preview Surface, Adobe Standard Material*
FBX	Supported Materials: 3ds Max Physical Mtl and Maya Stingray PBS
OBJ	.MTL file with valid (relative paths) links to texture data required; PBR materials within .MTL file need to conform to this syntax
STL	/
PLY	/
STEP	Enterprise license required
IGES	Enterprise license required
CTM	/

* Adobe Standard Material is only supported if the input file is a USD(Z) containing ASM nodes. USD(Z) outputs are supported, gltf/glb outputs have limited support.

Exporting a mesh to a file can be achieved using the command --export (short: -e). The currently supported formats for export are:

Export Format	Remarks
glTF	.glb and .gltf
VRM	VRM input data required; more info about VRM format here
USD/USDZ	.usd, .usda, .usdc, .usdz; Supported Materials: Preview Surface, Adobe Standard Material*
FBX	Supported Materials: 3ds Max Physical Mtl
OBJ	Output textures and PBR Material data saved within .MTL file conforming to this syntax
STL	/
PLY	/
CTM	/

* Adobe Standard Material is only supported if the input file is a USD(Z) containing ASM nodes. USD(Z) outputs are supported, gltf/glb outputs have limited support.

In addition, you can directly export an asset to a 3D HTML viewer, which is ready for publication on the Web, using the --export_web command (short: -w). While the --export command receives a filename as parameter, the --export_web command expects a directory name (will be created if not existing).

Texture	Single Value	Map Input	example
basecolor	Kd	map_Kd	map_kd material0_albedo.jpg
normal	/	norm	norm material0_normal.png
occlusion	/	occlusion	occlusion material0_occlusion.jpg
metallic	Pm	map_Pm	map_Pm material0_metallic.jpg
roughness	Pr	map_Pr	map_Pr material0_roughness.jpg
emission	Ke	map_Ke	map_Ke material0_emission.jpg

For proper OBJ import please use this syntax for PBR materials, see also table above. It is noteworthy here that the glTF format uses occlusion, metallic and roughness combined in one ORM texture. RapidCompact is able to read and write those for other formats as well if the maps are assigned correctly.

 

Simplifying and Texturing 3D Models

back to top  

Generating a Compact, Textured Representation

back to top

Generating a compact, textured 3D asset from a high-resolution input mesh is a complex task. Luckily, RapidCompact CLI has a single master operation for this purpose. The ratio behind this concept is to make this task as easy as possible, using a set of well-established default values (which can be altered using settings API).

When using compact, the input mesh is first simplified. Then, properties of the original mesh are preserved in texture maps, which are applied onto the low-resolution mesh. Creating texture maps this way is sometimes referred to as baking. There are several settings which can be used to configure the parameters of the whole process, the most relevant are typically the resolution of the mesh geometry and the resolution of the resulting texture maps. Setting the resolution of the resulting maps is straightforward using settings like baking:baseColorMapResolution and the respective variants of this setting for the other maps. However, the setting for the decimation parameter, entitled decimation:defaultTarget, requires some further explanation:

In contrast to regular commands, the commands for master operations start with a capital letter. Master operations can usually be broken down into several explicit commands. For example, instead of using compact, a compact, textured representation can also be obtained using a chain of explicit, regular commands, as shown in the following example:

         rpdx -i myMesh.ply --duplicate -d 10000  -u -b -w outWeb         

 

Decimating a Mesh

back to top

A common task when preparing 3D data for visualization is to decimate a 3D mesh. This process typically reduces the mesh geometry in order to speed up data transmission over networks and rendering performance inside an interactive 3D application. With RapidCompact CLI, this can be easily done using the decimate command:

The value of the following setting influences the result of the decimate command:

The following command can be used to remove duplicate vertices from a mesh:

 

Generating UV Mappings

back to top

RapidCompact CLI is a powerful tool for texture mapping, exposing several features of the RapidCompact Library. The UV mapping process typically involves several steps, and can mainly be divided into the following three stages:

1. Segmentation
2. Unwrapping
3. Atlas Packing

During segmentation, the 3D mesh geometry will be divided into charts that fulfill certain criteria (such as having disc topology). This step might be necessary, since not every mesh can be directly unwrapped by all kinds of parameterization algorithms. Each chart can then be unwrapped separately. During this step, the actual generation of 2D UV coordinates takes place. Finally, the third step arranges one or multiple charts in a (usually square) 2D domain, which is called a Texture Atlas.

RapidCompact CLI does not provide explicit commands for atlas packing. Instead, the atlas packing step is part of the unwrap command. This is motivated by the fact that an unwrapping of multiple charts without atlas packing, leading to overlaps inside the UV space, is usually not usable for very most applications, and may lead to unexpected results in many cases. Within the following, the unwrapping command and related settings (including such for texture packing) are illustrated.

Computing UV coordinates for a 3D mesh is for sure one of the most crucial steps within a texture mapping pipeline. RapidCompact CLI offers a fast, high-quality unwrapping which is by default configured preventing the occurance of any overlaps. The respective command (--unwrap) is further explained within the following.

The values of the following settings influence the result of the unwrap command:

 

Generating Textures

back to top

Generating occlusion maps:

The following setting influences the result and running time of the ambient occlusion computation:

Generating checker texture:

Generating base color and normal maps:

The following bake_maps command can be used to create texture maps for a low-resolution mesh, in order to visualize it with detailed surface properties from a corresponding high-resolution variant (such as normals, stored in a normal map). The process of creating such textures is also referred to as baking.

Apart from the baking:baseColorMapResolution setting and similar settings for resolutions of the other maps, the following settings influence the result of the bake_maps command:

 

Generating Images

back to top

Since it can easily be installed on servers an does not require a GPU, RapidCompact CLI can also be conveniently used to generate images of 3D models. This is useful, for example, when you have a large set of meshes and want to create thumbnail images. You can also use RC to render a turntable-like image series, rotating around the up-axis of a given mesh. Such an image series can then be used to display a pseudo-3D view of a 3D model (for example, inside a Web page). Image generation (or rendering) commands share the following common settings:

If a model should be rendered using a certain camera position and orientation, the following command set_view_matrix can be used:

If no view matrix is explicitly set, the model is rendered with the camera fitting to the scene, looking along the negative z-axis (if the system was not rotated). The commands for generating images are shown in the following.