Command line mode

From CloudCompareWiki
Jump to navigation Jump to search

Since version 2.3, CloudCompare can be used in "command line" mode.


By default, this mode only opens a small console window, applies the requested actions, and eventually saves the result in a file in the same directory(ies) as the input file(s). Commands are applied in the order they are written (like a state machine).

Available options (version 2.10.alpha)

Command Description
-SILENT enables silent mode (no console will appear)

Warning: must be first if required.

-O {filename} opens a file

If the file format is ASCII, optional settings are:

  • -SKIP {number of lines to skip} If set, CC will automatically skip the specified number of lines

For all formats, optional settings are (version 2.5.6 and above):

  • -GLOBAL_SHIFT {AUTO} or {x y z} If set, CC will either handle big coordinates automatically (AUTO) or apply the specified Global Shift vector (x,y,z)

Note: file type is automatically guessed from its extension.

-OCTREE_NORMALS {radius} Computes the normals for all loaded clouds with the specified radius.

Notes:

  • for now the local model is 'Height Function' and no default orientation is specified
  • if you have files containing structured clouds (e.g. PTX, FARO, DP, etc.), it may be more efficient to use the 'COMPUTE_NORMALS' option (see below)
-COMPUTE_NORMALS forces CC to compute normals at loading time (which is generally more robust) when importing files containing structured clouds (i.e. PTX, FARO and DP file for now). Normals are not computed by default.

Note: must be placed before the '-O' option.

-CLEAR_NORMALS Removes all normals from the loaded entities.
-ORIENT_NORMS_MST {number of neighbors} (Re)orient the normals of the loaded clouds with a Minimum Spanning Tree.

Note: Clouds without normals are simply ignored.

-MERGE_CLOUDS merges all loaded/generated clouds as one unique cloud.

Note: result is automatically saved by default (see the AUTO_SAVE command to change this).

-MERGE_MESHES merges all loaded/generated meshes as one unique mesh.

Note: result is automatically saved by default (see the AUTO_SAVE command to change this). This option is available since version 2.9.

-SS {algorithm} {parameter} applies a subsampling {algorithm} on the currently opened/generated cloud(s).

{algorithm} can be RANDOM, SPATIAL or OCTREE. Expected parameter is:

  • RANDOM: number of randomly selected points
  • SPATIAL: minimum distance between two points
  • OCTREE: subdivision level (between 1 and 10 in the standard version)

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this).
  • input clouds are now replaced by their subsampled version (since version 2.6.1)
-EXTRACT_CC {octree level} {minimum number of points per component} extracts the connected components from the currently opened/generated cloud(s).

{octree level} should be between 1 and 21.

Notes:

  • extracted components are automatically saved by default (see the AUTO_SAVE command to change this).
  • input clouds are replaced by the extracted components
-SAMPLE_MESH {method} {parameter} samples points on the loaded mesh(es).

For each mesh, a cloud will be generated (and will be added to the current loaded cloud set - i.e. further processing can be applied to this cloud).

{method} can be POINTS or DENSITY. Expected parameter is:

  • POINTS: the corresponding number of points
  • DENSITY: the corresponding surface density

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
  • this cloud can be used as input for cloud-to-cloud or cloud-to-mesh distances computation for instance.
-C2C_DIST computes cloud-to-cloud distances on the two first loaded/generated clouds (1st = compared / 2nd = reference).

Optional settings are:

  • -SPLIT_XYZ If set, 3 additional scalar fields will be generated (displacement along the 3 dimensions)
  • -MAX_DIST {value} to set a max distance above which CC won't have to search for a nearest neighbor (faster)
  • -OCTREE_LEVEL {value} to manually set the octree subdivision level at which the computation will be performed
  • -MODEL {local_model_type} {neighborhood_type} {neighborhood_size} to specify a local model:
    • {local_model_type} = LS / TRI / HF
    • {neighborhood_type} = KNN / SPHERE
    • {neighborhood_size} = neighbor count (if KNN) or sphere radius (if SPHERE)
  • -MAX_TCOUNT {thread count} to set the maximum number of threads to use

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
  • see below for more details
-C2M_DIST computes Cloud-to-Mesh distances between the first loaded/generated cloud (compared) and the first loaded mesh (reference).

Optional settings are:

  • -FLIP_NORMS to consider that normal vectors point inside the matter and not outside
  • -MAX_DIST {value} to set a max distance above which CC won't have to search for a nearest neighbor (faster)
  • -OCTREE_LEVEL {value} to manually set the octree subdivision level at which the computation will be performed
  • -MAX_TCOUNT {thread count} to set the maximum number of threads to use

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
  • see below for more details
-RASTERIZE -GRID_STEP {value} Rasterizes the loaded clouds by projecting them inside a regular grid.

Optional settings are:

  • -VERT_DIR {0/1/2} to specify the projection dimension (0=X / 1=Y / 2=Z) - default is 2 (Z)
  • -PROJ {MIN/AVG/MAX} to specify how the altitude of each cell is computed (minimum, average or maximum altitude of the projected points). Default is AVG (average)
  • -SF_PROJ {MIN/AVG/MAX} to specify how the SF value(s) of each cell are computed (minimum, average or maximum altitude of the projected points SF value(s)). Default is AVG (average)
  • -EMPTY_FILL {MIN_H/MAX_H/CUSTOM_H/INTERP} to specify how empty cells should be filled (MIN_H = min height / MAX_H = max height / CUSTOM_H = custom value - see CUSTOM_HEIGHT option below / INTERP = interpolate). Default behavior is 'leave cells empty'
  • -CUSTOM_HEIGHT {value} to define the custom height filling value (if the 'CUSTOM_H' strategy is used (see above)
  • -OUTPUT_CLOUD to output the result as a cloud (this is the default option if no other output format is defined)
  • -OUTPUT_MESH to output the result as a mesh
  • -OUTPUT_RASTER_Z to output the result as a geotiff raster (altitudes + all SFs by default, no RGB)
  • -OUTPUT_RASTER_RGB to output the result as a geotiff raster (RGB)

Notes:

  • if OUTPUT_CLOUD or OUTPUT_MESH is selected, the resulting entity will replace the original cloud in memory
-VOLUME -GRID_STEP {grid step} 2.5D estimation of the volume between two point clouds (the first is the ceiling, the second is the ground by default).

This tool outputs two files:

  • the volume calculation report (named VolumeCalculationReport.txt and saved next to the first file)
  • the 2.5D grid points with the 'height difference' as a scalar field and also as RGB colors (colors are generated with the default color scale of CC). The file is saved next to the previous one, and it has the same base name as the first file with '_HEIGHT_DIFFERENCE' appended at the end.

Optional settings are:

  • -VERT_DIR {0/1/2} to specify the projection dimension (0=X / 1=Y / 2=Z) - default is 2 (Z)
  • -CONST_HEIGHT {value} to use a constant height instead of the second cloud
  • -GROUND_IS_FIRST to invert the clouds order
  • -OUTPUT_MESH to output a mesh instead of a cloud

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
  • see below for more details
-STAT_TEST {distrib} {distrib parameters} {p-value} {neighbors count} applies a local statistical test based on the active scalar field all the of loaded/generated clouds.

{distrib} can be GAUSS or WEIBULL. Expected distribution parameters are:

  • GAUSS: the mean value and sigma
  • WEIBULL: a, b and the shift value

Note: result is automatically saved by default (see the AUTO_SAVE command to change this).

-COORD_TO_SF {dimension: X, Y or Z} exports the specified coordinate (dimension) to a scalar field.

Note: creates a new scalar field (or overwrite any existing one with the same name) and sets it active.

-FILTER_SF {minVal} {maxVal} filters all the loaded/generated clouds based on their active scalar field values.

A new cloud is created each time with only the points falling in the [minVal maxVal] interval.

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this).
  • input clouds are now replaced by their filteterd version (since version 2.6.1)

You can use special words in place of numbers that CC will replace by the actual SF values:

  • 'MIN' = min value
  • 'DISP_MIN' = min displayed value
  • 'SAT_MIN' = min saturation value
  • 'MAX' = max value
  • 'DISP_MAX' = max displayed value
  • 'SAT_MAX' = max saturation value
-DENSITY {sphere radius} computes the density (inside a sphere around each point) on the currently opened/generated cloud(s).

Optional setting:

  • -TYPE {density_type}: to specify the type of density to compute. {density_type} can be KNN (nearest neighbors count), SURFACE (surface density) or VOLUME (volume density).

Notes:

  • a new scalar field is created on each cloud
  • result is automatically saved by default (see the AUTO_SAVE command to change this)
-APPROX_DENSITY computes approximate density on the currently opened/generated cloud(s).

Optional setting:

  • -TYPE {density_type}: to specify the type of density to compute. {density_type} can be KNN (nearest neighbors count), SURFACE (surface density) or VOLUME (volume density).

Notes:

  • a new scalar field is created on each cloud.
  • result is automatically saved.
-ROUGH {kernel size} computes the roughness with a given kernel size on the currently opened/generated cloud(s).

Notes:

  • a new scalar field is created on each cloud
  • result is automatically saved by default (see the AUTO_SAVE command to change this)
-CURV {type} {kernel size} computes local curvature with a given kernel size on the currently opened/generated cloud(s).

{type} can be MEAN or GAUSS.

Notes:

  • a new scalar field is created on each cloud
  • result is automatically saved by default (see the AUTO_SAVE command to change this)
-SF_GRAD {euclidian} computes the gradient of the active scalar field (or the first one if none is active) on the currently opened/generated cloud(s).

The {euclidian} option specifies whether the scalar field is 'euclidian' (TRUE) - typically like a distance field - or not (FALSE).

Notes:

  • a new scalar field is created on each cloud
  • result is automatically saved by default (see the AUTO_SAVE command to change this)
-BEST_FIT_PLANE computes the best fitting plane on all loaded clouds.

Optional settings are:

  • -MAKE_HORIZ: will actually transform the loaded cloud(s) so as to make them 'horizontal'
  • -KEEP_LOADED: to keep the resulting plane(s) in memory as mesh(es)

Notes:

  • resulting planes are automatically saved
  • if MAKE_HORIZ is defined, result is automatically saved by default (see the AUTO_SAVE command to change this)
-APPLY_TRANS {filename} applies a 4x4 transformation matrix on the loaded entities (clouds or meshes). The matrix is read from a simple text file with the matrix rows on each line (4 values per lines, 4 lines).

Notes:

  • each entity will be replaced in memory by its transformed version
  • resulting entities are automatically saved by default (see the AUTO_SAVE command to change this)
-MATCH_CENTERS makes all the (bounding-box) centers of the loaded entities match. All the entities will move relatively to the first one (clouds are always considered first if clouds and meshes are loaded).

Note: result is automatically saved by default (see the AUTO_SAVE command to change this).

-DELAUNAY Triangulates the loaded clouds with 2.5D Delaunay triangulation. The triangulation is done in the (XY) plane by default.

Optional settings are:

Notes:

  • the resulting 'mesh' entity is automatically saved (see the AUTO_SAVE command to change this).
  • the clouds are automatically removed (from the 'loaded clouds' set).
-ICP Iterative Closest Point registration procedure.

Optional settings are:

  • -REFERENCE_IS_FIRST: by default the ICP registration process will take the first loaded entity as 'data' and the second as 'model' (clouds are always considered first). If you use this option their respective role will be inverted.
  • -MIN_ERROR_DIFF: to specify the min. error difference between two steps (default = 1e-6)
  • -ITER: to specify the number of iterations (in which case the 'MIN_ERROR_DIFF' option will be ignored)
  • -OVERLAP: to specify the percentage of (final) overlap (integer number between 10 and 100 - default = 100)
  • -ADJUST_SCALE: to enable the ICP registration with adaptive scale
  • -RANDOM_SAMPLING_LIMIT: to specify the number of points randomly sampled at each iteration (default = 20 000)
  • -FARTHEST_REMOVAL: to enable the research option that ignores points with the highest distances at each iteration
  • -DATA_SF_AS_WEIGHTS + {SF index}: to use a given scalar field as weights on the 'data' entity (index starts from 0 - the 'LAST' keyword can be used)
  • -MODEL_SF_AS_WEIGHTS + {SF index}: to use a given scalar field as weights on the 'model' entity (index starts from 0 - the 'LAST' keyword can be used)

Notes:

  • the 'data' entity in its final position is automatically saved (see the AUTO_SAVE command to change this).
  • the corresponding transformation matrix is automatically saved in a separate text file (always).
-CROP {Xmin:Ymin:Zmin:Xmax:Ymax:Zmax} Crops all loaded clouds inside or outside a given box.

Optional settings are:

  • -OUTSIDE: if defined only the points falling outside the input box will be kept (instead of inside by default).

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
  • each cloud will be replaced in memory by its cropped version
-CROP2D {ortho_dim} {n:number of vertices} X1 Y1 X2 Y2 ... Xn Yn Crops all loaded clouds inside or outisde a given 2D polyline. Cropping is done in a plane defined by its orthogonal dimension: X, Y or Z (i.e. coordinates along this dimension will be ignored).

Optional settings are:

  • -OUTSIDE: if defined only the points falling outside the input polyline will be kept (instead of inside by default).

Note:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
  • each cloud will be replaced in memory by its cropped version
-CROSS_SECTION {XML parameters file} Extracts one or multiple sections from the clouds or meshes.

Either the loaded clouds and/or meshes (see the -O option) can be used otherwise CC can load one or several files from a specified folder (use the 'FilePath' key).

See [1] for an example of XML parameter file.

Note:

  • output sections for meshes are 'clean' (i.e. triangles on the cutting borders are re-meshed)
  • output sections are automatically saved in sub-folders (they are not kept in memory)
-SOR {number of neighbors} {sigma multiplier} applies the SOR (Statistical Outlier Removal) filter on the loaded cloud(s).

For each cloud, a new one will be generated (and will replace the origin cloud).

Notes:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
-SF_ARITHMETIC {SF index} {operation} applies operations on a given scalar field of the loaded cloud/mesh.

SF2 = operation(SF)

The scalar-field index starts from 0. The user can use the keyword 'LAST' to designate the last scalar field.

Supported operations are:

  • sqrt (square root)
  • pow2
  • pow3
  • exp
  • log
  • log10
  • cos
  • sin
  • tan
  • acos
  • asin
  • atan
  • int (integer part)
  • inverse

Notes:

  • the updated cloud/mesh is automatically saved (see the AUTO_SAVE command to change this)
  • a new scalar field is created
-SF_OP {SF index} {operation} {value} applies an arithmetic operation on a given scalar field of the loaded cloud/mesh and with a given scalar value.

SF = SF (+,-,*,/) VALUE

The scalar-field index starts from 0. The user can use the keyword 'LAST' to designate the last scalar field.

Supported operations are:

  • add
  • sub
  • mult
  • div

Notes:

  • the updated cloud/mesh is automatically saved (see the AUTO_SAVE command to change this)
  • the modification is done in place (i.e. the scalar field is directly modified)
-CBANDING {dim} {freq} Applies color banding to all loaded entities (clouds and meshes). The user must specify the dimension (dim = X, Y or Z) and the frequency (in Hz, as an integer).

Note:

  • result is automatically saved by default (see the AUTO_SAVE command to change this)
-C_EXPORT_FMT {format} Specifies the default output format for clouds. Format can be one of the following: ASC, BIN, PLY, LAS, E57, VTK, PCD, SOI, PN, PV.

Optional settings are:

  • -PREC [precision]: to specify the numerical output precision (for ASCII files only). precision is a positive integer (default = 12).
  • -SEP [separator]: to specify the separator character (for ASCII files only). separator can be one of the following string: SPACE, SEMICOLON, COMMA or TAB (default = SPACE).
  • -ADD_HEADER: to add a header with each column's name to the saved file (for ASCII files only).
  • -ADD_PTS_COUNT: to add the number of points at the beginning of the saved file (for ASCII files only).
  • -EXT [extension]: to specify the file extension (typically different from the default one for the chosen format)

WARNING: the ADD_HEADER and ADD_PTS_COUNT options are broken in the 2.6.2 version. Use the latest 2.6.3 beta version instead.

-M_EXPORT_FMT {format} Specifies the default output format for meshes. Format can be one of the following: BIN, OBJ, PLY, STL, VTK, MA, FBX.

Optional settings are:

  • -EXT [extension]: to specify the file extension (typically different from the default one for the chosen format)
-FBX_EXPORT_FMT {format} Specifies the default output format for FBX meshes. Must be specified in addition to M_EXPORT_FMT if FBX format is chosen. Format can be one of the following: FBX_binary, FBX_ascii, FBX_encrypted, FBX_6.0_binary, FBX_6.0_ascii, FBX_6.0_encrypted.

Note: if the input format is not supported by the current implementation, a list of available formats will be output in the console.

-PLY_EXPORT_FMT {format} Specifies the default output format for PLY files. Format can be one of the following: ASCII, BINARY_BE (big endian) or BINARY_LE (little endian).

Note: default output format is binary (LE/BE depending on the current OS)

-NO_TIMESTAMP to prevent CC from generating an automatic suffix (timestamp) for output file name (warning: this make the name of an output file predictable but if the file already exists it will be overwritten).
-BUNDLER_IMPORT {filename} imports a Snavely's Bundler file.

Bundler import through the command line is mainly meant to generate ortho-rectified versions of input images directly on disk. Optional settings are:

  • -ALT_KEYPOINTS [filename]: load alternative keypoints from file filename
  • -SCALE_FACTOR [value]: sets image scale factor that has been used during keypoints generation
  • -COLOR_DTM [vertices count]: generates colored vertices of a pseudo-DTM with approximately 'vertices count' elements (in command line mode, vertices are automatically saved to 'colored_dtm_vertices.bin' next to ortho-rectified images)
  • -UNDISTORT: enables images undistortion

Note: see below for more details.

-DROP_GLOBAL_SHIFT Removes the Global Shift information from all loaded entities.
-SET_ACTIVE_SF {index} Sets the active scalar field index (for all loaded clouds).

Note:

  • scalar field indexes start at 0 ('-1' means 'no SF enabled')
-REMOVE_ALL_SFS Removes all scalar fields (from all loaded clouds or meshes).

Note:

  • entities are not automatically saved after this command (you can use -SAVE_CLOUDS or -SAVE_MESHES explicitly)
-AUTO_SAVE {ON/OFF} Enables (ON) or disables (OFF) automatic backup of clouds and meshes at each step (you'll have to manually call -SAVE_CLOUDS or -SAVE_MESHES at the right time/position in your command).
-SAVE_CLOUDS Saves all currently loaded clouds (note that this is not necessary by default as all modified or newly generated cloud are automatically saved).

Optional settings are:

  • ALL_AT_ONCE: saves all clouds in a single file (the current output format must support it!)
-SAVE_MESHES Saves all currently loaded meshes (note that this is not necessary by default as all modified or newly generated meshes are automatically saved).

Optional settings are:

  • ALL_AT_ONCE: saves all meshes in a single file (the current output format must support it!)
-CLEAR closes all currently loaded entities.
-CLEAR_CLOUDS closes all currently loaded clouds.
-CLEAR_MESHES closes all currently loaded meshes.
-POP_CLOUDS removes the last loaded cloud.
-POP_MESHES removes the last loaded mesh.
-LOG_FILE {filename} logs all command output messages in a given file.

Example 1

CloudCompare -O myhugecloud.bin -SS SPATIAL 0.1

This will open file myhugecloud.bin then apply spatial subsampling with a 0.1 step (e.g. in meters). The output file will be myhugecloud_SPATIAL_SUBSAMPLED_YYYY-MM-DD_HHhMM.bin.

Example 2

CloudCompare -O myhugecloud1.bin -SS SPATIAL 0.1 -O 'myhugecloud2.bin' -SS RANDOM 1000000 -CLEAR_ALL -O 'myhugecloud3.bin' -SS OCTREE 9

This will open file myhugecloud1.bin then apply spatial subsampling with a 0.1 step (e.g. in meters).
Then it will open file myhugecloud2.bin and apply to both files random subsampling (1 000 000 points each).
Then it will close the two first files.
Eventually it will open file myhugecloud3.bin and apply octree based subsampling (level 9).

The output files will be: myhugecloud1_SPATIAL_SUBSAMPLED_YYYY-MM-DD_HHhMM.bin, myhugecloud1_RANDOM_SUBSAMPLED_YYYY-MM-DD_HHhMM.bin, myhugecloud2_RANDOM_SUBSAMPLED_YYYY-MM-DD_HHhMM.bin and myhugecloud3_OCTREE_level_9_SUBSAMPLED_YYYY-MM-DD_HHhMM.bin

Cloud-to-cloud distance

CloudCompare -o cloud1.bin -o cloud2.asc -c2c_dist -split_xyz -model HF SPHERE 50.0

CC will load cloud1.bin and cloud2.asc, then compute the distance from cloud1 (compared) relatively to cloud2 (reference) with a height function (quadric) computed on all the neighbors falling in a sphere of radius 50.0 around each point of cloud1. On output a file cloud1_C2C_DIST_YYYY-MM-DD_HHhMM.bin will be generated (with the resulting distances as first scalar field and the 3 components of the corresponding displacement vector along X, Y and Z as additional scalar fields).

Note: this cloud stays in memory and can be processed further (with -FILTER_SF for instance).

Cloud-to-mesh distance

CloudCompare -o cloud1.bin -o mesh.obj -c2m_dist

CC will load cloud1.bin and mesh.obj, then compute the distance from cloud1 (compared) relatively to mesh (reference). On output a file cloud1_C2M_DIST_YYYY-MM-DD_HHhMM.bin will be generated (with the resulting distances as scalar field).

Note: this cloud stays in memory and can be processed further (with -FILTER_SF for instance).

Bundler import

CloudCompare -BUNDLER_IMPORT bundle.out -COLOR_DTM 1000000

This will generate all ortho-rectified versions of the images declared in 'bundle.out', as well as the colored vertices of a pseudo-DTM constructed from the keypoints.

(Mesh) format conversion

CloudCompare -M_EXPORT_FMT FBX -FBX_EXPORT_FMT FBX_Binary -O Foot.ply -NO_TIMESTAMP -SAVE_MESHES

This will open the file named 'Foot.ply' then save it in FBX binary format (same base filename, without any decoration: i.e. Foot.fbx)

Retrieved from "https://www.cloudcompare.org/doc/wiki/index.php?title=Command_line_mode&oldid=47161"