Available Commands

info

This page is a work in progress. Please refer to our legacy CLI docs for most up to date version.

Available Commands

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

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.>
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
colorize_vertex_ao	0	-i foo.obj --colorize_vertex_ao [...]	computes per-vertex ambient occlusion more
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

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

Generating a Compact, Textured Representation

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).

Turning a high-resolution input mesh into a compact 3D asset, preserving the original appearance. Left: Original mesh, consisting of 551,260 triangles. Right: Compact version with 25,000 triangles, which is less than 5% of the original geometry. The decimation of less complex input data such as meshes from 3D scans can result in 0,1% and less of the original mesh size.

Master Operation:	compact (c)
Example:	rpdx -i myMesh.ply -c -w outWeb
Description:	Creates a geometrically decimated, textured representation from a high-resolution mesh. The input mesh may have color or texture information associated, which will be conserved as good as possible in the result, using texture maps. To preserve surface details, a normal map is created. Optionally (via ao settings), ambient occlusion may be computed when no original color information is available.

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:

Setting Name:	decimation:defaultTarget
Setting Type:	String
Valid Values:	<number>[%], v:<number>[%], f:<number>[%]
Default Value:	v:10000
Description:	Specifies the default target parameter used for mesh decimation. This can be an absolute number, or a percentage, regarding either the vertices or faces of the mesh. For example, v:5% decimates the mesh geometry to 5% of the original vertices. The format of this setting is identical to the argument format of the decimate command.

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

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:

Decimation of an input mesh to 1% of its original vertices, using different methods. From left to right: Original mesh, result using edge-length based decimation, result using Quadric-based decimation.

Command:	decimate (d)
Argument:	decimation target (number or percentage of vertices or faces)
Example:	rpdx -i myMesh.ply -d v:1% -e result.ply
Description:	Decimates a mesh until a given target criterion is reached. This can be an absolute number, or a percentage, regarding either the vertices or faces of the mesh. With prefix v:, the number / percentage of vertices is used as criterion, while prefix f: specifies that the following is a number / percentage of faces. If no prefix is given, the argument is interpreted with respect to vertices. The above example decimates the mesh to 1% of its original vertices.

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

Setting Name:	decimation:method
Setting Type:	String
Valid Values:	quadric, edgeLength
Default Value:	quadric
Description:	Specifies the method to be used for mesh decimation. The quadric-based ("quadric") decimation usually gives good results. The edge-length based decimation is slightly faster, and it is well-suited if you aim at obtaining a highly homogeneous mesh.

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

Command:	remove_duplicate_vertices
Example:	rpdx -i myMesh.ply --remove_duplicate_vertices -e result.ply
Description:	Removes duplicate vertices from the mesh. During this step, geometry is re-created, and all surface attributes, such as texture or vertex colors, are discarded.

Generating UV Mappings

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.

Segmenting a mesh into optimized charts for texturing.

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.

Computing UV coordinates for a segmented mesh. Left: segmented 3D mesh. Right: UV atlas.

Command:	unwrap
Example:	rpdx -i myMesh.ply -u -e myMesh-UV.obj
Description:	Computes a UV mapping for a segmented mesh (or for a single mesh with disc topology). Charts are first unwrapped and then packed into a texture atlas.

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

Setting Name:	unwrapping:method
Setting Type:	String
Valid Values:	conformal, fastConformal, isometric, forwardBijective, fixedBoundary
Default Value:	fastConformal
Description:	Specifies the method to be used for UV unwrapping. The different methods are: conformal: A very fast method, producing results of good quality. This method tries to avoid stretch by minimizing the error in angles. It may produce self-overlaps, so make sure to enable unwrapping:cutOverlappingPieces if you want overlap-free UVs. fastConformal: Sightly faster than conformal, producing a good approximation of the conformal method. It may also produce self-overlaps, so make sure to enable unwrapping:cutOverlappingPieces if you want overlap-free UVs. isometric: A balanced method, producing results of best possible quality. This method tries to avoid stretch by minimizing the error in angles and areas. It may produce self-overlaps, so make sure to enable unwrapping:cutOverlappingPieces if you want overlap-free UVs. forwardBijective: A sophisticated method, producing results of high possible quality that are guaranteed to have no overlaps. This method tries to avoid stretch by minimizing the error in angles and areas. Since it never produces self-overlaps, a separate cutting step is not necessary. fixedBoundary: A fast, very basic method, pinning the boundary of the UVs to a circle and then computing interior UV coordinates. Results are guaranteed to have no self-overlaps. Due to the circular shape, results will only have low stretch if the 3D shape has an approximately circular boundary.

Setting Name:	packing:chartPadding
Setting Type:	Real
Valid Range:	[0, 1)
Default Value:	~0.0005 (1.0/2048)
Description:	Specifies the amount of padding to be used around each chart within the UV atlas. The value is interpreted relative to the unit range of the atlas. This means that, for example, a value of 1/1000 will produce a padding of one thousandth of the atlas' size around each chart. If the constraint cannot be fulfilled (for example, because there are too many charts), it will be relaxed accordingly.

Generating Color Information and Textures

The following commands can be used to create vertex colors or texture maps:

Storing computed AO (Ambient Occlusion) values in vertex colors or as a texture. Left: Compact model without vertex colors and textures. Center: Asset with automatically baked normal map. Right: Asset with AO.

Command:	colorize_vertex_ao
Example:	rpdx -i myMesh.ply --colorize_vertex_ao -e myMesh-ao.ply
Description:	Computes computed AO (Ambient Occlusion) at each vertex and colors the vertices accordingly.

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

Setting Name:	ao:vertexSamples
Setting Type:	Integer Number
Valid Range:	[1, 1024]
Default Value:	100
Description:	Specifies the number of samples taken for each vertex when generating ambient occlusion values. Larger values result in more precise occlusion computation, at the cost of longer computation times.

Command:	set_checker_texture
Example:	rpdx -i mesh-UVs.obj --set_checker_texture -e mesh-checker.obj
Description:	Attaches a checkerboard texture to the 3D asset. This is primarily useful to visualize the properties (stretch, scale and direction) of a UV mapping.

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.

Normal map (object-space) and Albedo map (base color) for a textured low-resolution mesh, generated from the corresponding high-resolution original. For illustration purposes, this texture atlas was generated without inpainting.

Command:	bake_maps
Example:	rpdx -i highpoly.obj -i lowpoly-UV.obj -b -w outWeb
Description:	Transfers attributes of a source asset into texture maps of destination mesh, using the UV mapping of the destination asset. The second highest asset of the stack acts as source asset, the topmost asset of the stack acts as destination asset. Usually, a normal map and a base color / albedo map are created. If the destination asset does not have color information (such as vertex colors or textures), it is possible to create the base color / albedo texture using ambient occlusion, computed on the source asset.

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:

Setting Name:	inpainting:radius
Setting Type:	Integer
Valid Values:	[0, 32]
Default Value:	32
Description:	Specifies the radius, in pixels, to be used for texture inpainting around each chart.

Setting Name:	ao:enabled
Setting Type:	Flag
Valid Values:	true, false
Default Value:	false
Description:	Specifies if generation of AO texture maps is enabled.

Setting Name:	ao:replaceMissingAlbedo
Setting Type:	Flag
Valid Values:	true, false
Default Value:	true
Description:	Specifies if AO should be used to replace a missing albedo / base color texture, in case no such texture is available on the source asset during baking. If this flag is switched off, AO will always be written to a separate, dedicated texture map.

Setting Name:	ao:textureSamples
Setting Type:	Integer Number
Valid Range:	[1, 64]
Default Value:	8
Description:	Specifies the number of samples taken for each texel when generating an ambient occlusion texture. Larger values result in more precise occlusion computation, at the cost of longer computation times.

Setting Name:	ao:filterRadius
Setting Type:	Real
Valid Range:	[0, 16]
Default Value:	5.0
Description:	Specifies the filter radius used for smoothing the ambient occlusion texture (if any). Set the filter radius to 0 to disable smoothing.

Generating Images

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:

Setting Name:	rendering:imageWidth (similar: rendering:imageHeight)
Setting Type:	Integer Number
Valid Range:	[1, 8192]
Default Value:	1024
Description:	Specifies the width (similar: height) for rendered images.

Setting Name:	rendering:background
Setting Type:	String
Valid Values:	transparent, white, black, gradientGray
Default Value:	transparent
Description:	Specifies the background to be used when rendering images.

Setting Name:	rendering:showBackFaces
Setting Type:	Flag
Valid Values:	true, false
Default Value:	false
Description:	Specifies whether faces with a surface normal pointing away from the viewer ("backfaces") should be rendered.

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

Command:	set_view_matrix
Shorthand:	v
Argument:	matrix in format "m00 m01 m02 m03 m10 m11 m12 m13 m20 m21 m22 m23"
Example:	rpdx -i foo.obj -v "1 0 0 0 0 1 0 0 0 0 1 -1000" --render_image foo.png
Description:	Sets the view matrix, used for rendering, to the given matrix. The 3x4 matrix in row major format must be specified as a single, whitespace-separated string, wrapped in quotes.

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.

Images generated with different backgrounds. Background names from left to right: "transparent", "white", "black", "gradientGray".

Command:	render_image
Shorthand:	none
Argument:	filename of the resulting image file
Example:	rpdx -i myMesh.ply --render_image mesh.png
Description:	Renders an image of a mesh and stores it to the given image file. Supported image formats are PNG and JPEG.

Command:	render_turntable
Argument 1:	directory for images
Argument 2:	number of views / images to render
Example:	rpdx -i foo.obj --render_turntable meshTT 32
Description:	Renders a turntable-like image series by centering the asset and rotating the view around the up-axis. The resulting images will be stored in PNG format.