Command Line Interface

Many features of RealityCapture can be used directly via the command line or by running a script. They are passed to the application as parameters of RealityCapture.exe and executed in a sequence. The process behaves in a similar way as if the features were called using the GUI. The application will launch and you can interact with it as usual during the calculations.

You can run a command sequence in the Windows Command Prompt or by running a file with .bat extension. This is an example of the command sequence. It starts by launching the application with its full path. Every command begins with a hyphen and is followed by no, one or more parameters.

"C:\Program Files\Capturing Reality\RealityCapture\RealityCapture.exe" -load C:\MyFolder\MyProject.rcproj -selectMaximalComponent -calculateNormalModel -simplify 1000000 -save C:\MyFolder\MyProject.rcproj -quit

The full application path can be replaced by a simple RealityCapture.exe - if you store the path in a system variable path.

TIP: Add the following line to the beginning of your script in order to temporarily add the RealityCapture folder to the path (until the end of the command-line session).
set PATH=%PATH%;C:\Program Files\Capturing Reality\RealityCapture\
RealityCapture.exe -load ... -quit

Licenses

The following commands and examples in this section can be used for activation of the standard licenses or using the PPI version of RealityCapture.

Command Name Required Parameter Optional Parameter Description
activate activationToken Activate license using an activation token (activationToken) generated in your MY account on our webpage - section Licenses. The license will be activated and renewed with a selected activation period. You can disable the automatic activation renewal using -set "appLicenseAutoRenew=false". See more information here. Example:
Realitycapture.exe –activate 9002677B0FBF8BA63E720835391BBB75A1824B0BDF680751103774AC33B5D5DB
getLicense pin|pinCertificateFile Get PPI licenses for all images in the scene. Both pin and its pinCertificateFile can be generated here.
importLicense mylicense.rclicense Import input licenses stored in the filename.rclicense file. The file may contain one or more licenses. All of them will be imported to the system. The application will use them instead of contacting the licensing server if licenses for all used inputs are contained. Otherwise the licensing server is contacted. Example:
Realitycapture.exe –importLicense "c:\licenses\mylicense.rclicense"
exportLicense mylicense.rclicense true/false Use this command to export all currently imported licenses. By exporting licenses, you store the rights to process inputs. This typically means offline, free-of-charge processing of the same inputs or a subset of these inputs in the future. Use the optional parameter set to true if you wish to append the exported license to the existing mylicense.rclicense file. The default value is false. Example:
Realitycapture.exe –exportLicense "c:\licenses\mylicense.rclicense"

Basic Project and Image Commands

The following are the most basic commands that let you control the current project, the application itself, and add images.

Command Name Required Parameter Optional Parameter Description
headless Hides user interface. Find more about this command here.
newScene Create a new empty scene.
load MyProject.rcproj recoverAutosave|deleteAutosave Load an existing project from the MyProject.rcproj file. Use optional parameters to define the action if there is an autosaved file present for this project. Using recoverAutosave will open the autosaved project, while deleteAutosave will delete the autosaved project and load the original one. More information about Autosave feature here.
To set the preference globally for all projects, use set command with appAutoSaveCliHandling key. Find more information in the section CLI Settings Keys & Values.
save MyProject.rcproj Save the current project to its original location or save as MyProject.rcproj.
add imageName Add an image or image list.
addFolder folderName Add all images in the specified folder. In order to include also subdirectories, use command set with a key appIncSubdirs as follows: -set "appIncSubdirs=true". Find more information in the section CLI Settings Keys & Values.
importVideo videoFileName
extractedVideoFramesLocation
jumpsLength
Import frames extracted from a video (videoFileName including the path). The frames are extracted into a folder (extractedVideoFramesLocation) using an interval between frames defined by the jumpsLength (in seconds).
importLeicaBlk3D fileName Import an image sequence with .cmi extension (fileName including path) captured by Leica BLK3D.
importLaserScan laserScanName params.xml Add a laser scan or a laser-scan list using the current settings or the settings from the params.xml file (optional parameter). You can export these settings from the application in the Laser Scan Import dialog.
importLaserScanFolder folderName params.xml Add all laser scans in the specified folder using settings from the params.xml file. You can export these settings from the application in the Laser Scan Import dialog.
importHDRimages fileName|folderName|imageList params.xml Import HDR image (imageName), list of images (imageList) or all images from a folder (folderName) using the current settings or the settings from params.xml. You can export these settings from the application in the 16-bit/HDR Images Import dialog.
addImageWithCalibration fileName
xmpFileName
Import an image as well as the corresponding XMP file. Use whole paths to the files.
importImageSelection fileName Select scene images and/or laser scans listed in a file (fileName including the path).
selectImage imagePath|regexp set
union
sub
intersect
toggle
Select a specified image (imagePath) or images defined by regular expression (regexp). See below examples. One of the optional parameters may be used to more select images with more flexibility.
selectAllImages Select all images in the project.
deselectAllImages Deselect all images in the project.
invertImageSelection Invert the current image selection.
setImageLayer index pathImage layerType Set the layer from the image defined with the pathImage parameter (path to the layer image) to the image defined with the index parameter. Index corresponds to the image order in the 1Ds view and it starts at 0 (zero). The layerType parameter defines which layer to set onto the chosen image (e.g. mask, texture).
setImagesLayer pathImage layerType Set the layer from the image defined with the pathImage parameter (path to the layer image) to the selection of images. The layerType parameter defines which layer to set onto the selected images (e.g. mask, texture).
removeImageLayer layerType Remove the layers corresponding to the layerType parameter (e.g. mask, texture) from the selected images.
importCache folderName Import resource cache data from the specified folder.
clearCache Clear the application cache. You must save the project before clearing the application cache.
execRCCMD Commands.rccmd Execute commands listed in the .rccmd file. You can find the instructions on how to write the file in the section Commands Outside Command Prompt.
quit Quit the application

Example of input licensing

License your inputs using a certificate file and export a license into a license file:

-addFolder C:\userName\Documents\datasets\datasetName ^
-getLicense C:\userName\Documents\datasets\datasetName\pinCert\pin_cert.txt ^
-exportLicense C:\userName\Documents\datasets\datasetName\datasetName-lic\ppi-licenses.rclicense

TIP: In batch scripting you can break the line with ^ sign and continue the command sequence on the next line so that the CLI processes it as one line.

There are 2 options for importing images and the RealityCapture PPI license simultaneously, which are in separate folders:


When images and the PPI license are in the same folder, use this command for their import:

RealityCapture.exe -addFolder C:\userName\Documents\datasets\datasetName\

Examples of image selection

Select an image specified by direct path:

-selectImage D:\sample\Images\IMG_0018.JPG

Select images with "DSC" in their name:

-selectImage g/DSC/

Select images that contain "2" and "1" and some other character in between (e.g. image_1251.jpg):

-selectImage g/2.1/

Select every image that ends with even number and has .jpg extension (e.g. 222.jpg or img_0018.jpg):

-selectImage g/[02468]\.jpg/

Select every image that contains "DSC", ends with even number and has .jpg extension (e.g. img_DSC_222.jpg or DSC_14.jpg):

-selectImage g/DSC.*[02468]\.jpg/

Command used to select image(s) can have one of the few optional parameters:

Delegate commands

You can use these commands to delegate actions to a certain RealityCapture instance. You can find out more about delegation of commands here.

Command Name Required Parameter Optional Parameter Description
setInstanceName instanceName Assign a name to a RealityCapture instance.
delegateTo instanceName|* Delegate a command or a sequence of commands to a specific instance of RealityCapture (instanceName) or to the first available instance (using the * symbol as a parameter).
waitCompleted instanceName|* Pause execution of other commands until the current process is finished in a specified instance of RealityCapture (instanceName) or in the first available instance (using the * as a parameter).
getStatus instanceName|* Return the progress status of a running process in a specified instance of RealityCapture (instanceName) or in the first available instance (using the * symbol as a parameter).
pauseInstance instanceName|* Pause a currently running process in a specified instance of RealityCapture (instanceName) or in the first available instance (using the * symbol as a parameter).
unpauseInstance instanceName|* Unpause a currently paused process in a specified instance of RealityCapture (instanceName) or in the first available instance (using the * symbol as a parameter).
abortInstance instanceName|* Abort a currently running process in a specified instance of RealityCapture (instanceName) or in the first available instance (using the * symbol as a parameter). If processing is done using the CLI commands, all processes after the running process will also be aborted.
queryScenePrice queryScenePrice|* inputsRemaining
price
priceReal
messageCode
textMessage
Check the amount of credits needed (and price in USD) for your inputs to be licensed in a specified instance of RealityCapture (instanceName) or in the first available instance (using the * symbol as a parameter). You can choose which information you want to see by using certain optional parameters.

Commands for Selected Images

The following enable you to set some preferences for further image processing.

Command Name Required Parameter Optional Parameter Description
setFeatureSource 0|1|2 Define a feature source mode for the selected images:
0 - Merge using overlaps,
1 - Use component features,
2 - Use all image features.
enableAlignment true|false Enable/disable selected images in the registration process.
enableMeshing true|false Enable/disable selected images in the model computation/meshing.
enableTexturingAndColoring true|false Enable/disable selected images during the coloring and texture calculation.
weightInTexturing <0,1> Set weight for selected images during the coloring and texture calculation.
setDownscaleForDepthMaps integer Set a downscale factor for depth-map computation for the selected images.
enableInComponent true|false Enable selected images in meshing and continue. Applicable only for the registered images.
setCalibrationGroupByExif Set the calibration group of all inputs based on their Exif.
lockPoseForContinue true|false Set relative camera pose unchanged for the selected images during the next registration. Applicable only for the registered images.
setPriorCalibrationGroup number Set a prior calibration group for the selected images:
-1 - do not group,
another number - group into the same calibration group.
setPriorLensGroup number Set a prior lens group for the selected images. Using -1 means do not group, any other number means to group the selected images into the same distortion group.
editInputSelection "key=value" Edit the settings of the selected inputs based on the value in the Selected inputs panel or its key. More information can be found here.

Code Examples

All the scripts are written in Windows command-line language. Let us say that you write a batch script stored in a C:\MyFolder and you want to load a project C:\MyFolder\PlainProject.rcproj, add images from the folder C:\MyFolder\Images, save progress to MyProject.rcproj and quit.

set PATH=%PATH%;C:\Program Files\Capturing Reality\RealityCapture\
RealityCapture.exe -load C:\MyFolder\PlainProject.rcproj -addFolder C:\MyFolder\Images\ -save C:\MyFolder\MyProject.rcproj -quit

To improve the legibility (in case the path is long) and flexibility of your code, we recommend you to store the working folder in an environment variable.

set PATH=%PATH%;C:\Program Files\Capturing Reality\RealityCapture\
set MyPath=C:\MyFolder
RealityCapture.exe -load %MyPath%\PlainProject.rcproj -addFolder %MyPath%\Images\ -save %MyPath%\MyProject.rcproj -quit

Adding an image list or a single image works in the same manner.

set PATH=%PATH%;C:\Program Files\Capturing Reality\RealityCapture\
set MyPath=C:\MyFolder
RealityCapture.exe -load %MyPath%\PlainProject.rcproj -add %MyPath%\images.imagelist -add %MyPath%\Images\image_123.jpg -save %MyPath%\MyProject.rcproj -quit

NOTE: An image list is a simple list of full-path names separated by line breaks. You can obtain one using RealityCapture by clicking on Alignment / Export / Image List.

Using the -newScene command is usually not necessary, since the application launches with a new scene. But it can be useful to start a new project without a need to relaunch the application.

We will omit the first two lines, which set the environment variables, in the rest of the tutorial and assume that you have them covered.

NOTE: In batch scripting, you always need to break a line of code with ^ in case you want to continue the sequence of RealityCapture commands on the next line and process them as one.
Any lines beginning with #, //, REM or rem are skipped. You can use these symbols before a portion of text to mark it as a code comment, for instance: // I am a comment.

Continue

Using CLI with .rccmd

Delegation of Commands

On delegating commands into an opened instance of RealityCapture

Alignment Commands

Commands for alignment and component handling

Reconstruction Commands

Model calculation via the command line

Model Tools' Commands

Further model processing via the command line

Settings' Commands

Application settings and behaviour

Error Handling Commands

Commands for handling potential errors

See also: