CLI Migration Guide
Introduction
This guide covers the process of upgrading the RapidCompact CLI v1.4.0-v6.x.x (legacy) to the 3D Processor CLI v7.0.0 and newer.
It also compares the differences between the versions in terms of commands and general CLI usage, settings and schemas, as well as the JSON configuration settings files.
Upgrading to the 3D Processor CLI
Coming Soon ✨✨✨
Setting up the 3D Processor CLI
Coming Soon ✨✨✨
CLI Commands Differences
The 3D Processor CLI (v.7.0.0 +) and available command line arguments are NOT compatible with older versions of the RapidCompact CLI (legacy).
RapidCompact CLI Commands (legacy)
Coming Soon ✨✨✨
3D Processor CLI Commands
Coming Soon ✨✨✨
CLI Settings Differences
The 3D Processor CLI (v.7.0.0 +) and corresponding Configuration Settings files (JSON) are NOT compatible with older versions of the RapidCompact CLI (legacy).
RapidCompact CLI Settings (legacy)
The RapidCompact CLI v1-6 does not have a settings schema, settings are directly ingested, potentially resulting in Errors or Warnings.
Settings have no hierarchy (all settings are on the same level).
Settings which exist, but are not specified in the configuration file are still applied in their default state.
For an automated conversion of the CLI commands and settings please refer to the last section of this guide below.
Example (all CLI v6.10.0 compact (general optimization) and decimation category settings with defaults):
{
"compact:addUVsToTiledMeshes": false,
"compact:aggregateUVs": false,
"compact:allowRectangularPOTTextures": false,
"compact:animationSimplification": "none",
"compact:atlasingFactor": 1,
"compact:atlasingMode": "separateAlpha",
"compact:baseColorFlatTexThreshold": 0,
"compact:defaultFlatTexThreshold": 0,
"compact:displacementFlatTexThreshold": 0,
"compact:emissiveFlatTexThreshold": 0,
"compact:materialNamingScript": "",
"compact:metallicFlatTexThreshold": 0,
"compact:nodeNamingScript": "",
"compact:normalsFlatTexThreshold": 0,
"compact:occlusionFlatTexThreshold": 0,
"compact:pixelsPerUnitLength": 0,
"compact:powerOfTwoTextures": "ceil",
"compact:quality": "default",
"compact:removeInvisibleGeometry": false,
"compact:removeSmallFeatures": "",
"compact:roughnessFlatTexThreshold": 0,
"compact:specularFlatTexThreshold": 0,
"compact:splitMode": "auto",
"decimation:boundaryPreservationFactor": 0.5,
"decimation:collapseDistanceThreshold": 0.0050000000000000001,
"decimation:collapseUnconnectedVertices": true,
"decimation:defaultTarget": "f:20000",
"decimation:method": "quadric",
"decimation:preserveCommonMeshBorders": true,
"decimation:preserveMaterialBorders": false,
"decimation:preserveNormals": false,
"decimation:preserveTiledUVs": false,
"decimation:preserveTopology": false,
"decimation:preserveUVs": false,
"decimation:probQuadricStddev": 0,
"decimation:recomputeNormals": true,
"decimation:tiledUVThreshold": 1.5
}
All other settings under the following categories are still being applied with their defaults:
ao, baking, compact, export, flattening, general, geoCompression, import, inpainting, logging, material, packing, remeshing, rendering, segmentation, unwrapping, visibility
Read more about RapidCompact CLI legacy settings here
3D Processor CLI Settings
Settings are depending on 3 new schemas:
| Settings Category | Schema | Description |
|---|---|---|
| 3D Processing | 3D Processing Schema | Direct operations on the 3D Data, such as Optimization, Compression, etc. |
| Rendering | Rendering Schema | Rendering of 3D Data using the RapidPipeline PBR Renderer |
| System | System Schema | System Settings - only relevant for the 3D Processor CLI |
The major differences here are that there are hierarchical settings structures with 2 distinct groups:
- Objects (setting categories)
- Settings (within objects)
Example (CLI v7.0.0 optimize and decimation category settings file example with defaults):
{
"optimize": {
"3dModelOptimizationMethod": {
"meshAndMaterialOptimization": {
"decimator": {
"target": {
"faces": {
"value": 1
},
"deviation": {
"value": 0.0
}
},
"materialOptimization": {
"materialMerger": {
"materialRegenerator": {
"uvAtlasGenerator": {
"textureBaker": {
"normalMap": {}
}
}
}
}
},
"preserveTopology": false,
"preserveNormals": false,
"preserveMeshBorders": true,
"preserveMaterialBorders": false,
"collapseUnconnectedVertices": true,
"boundaryPreservationFactor": 0.50,
"collapseDistanceThreshold": 0.005,
"method": "quadric"
}
}
}
},
"export": [
{
"fileName": "",
"textureMapFilePrefix": "",
"discard": {},
"format": {
"gltf": {
"pbrMaterial": {}
}
}
}
]
}
As per 3D Processing Schema the example above is only one variation of expressing 3D optimization with mesh decimation.
Read more about possible configuration settings within optimize here.
In addition, note that the export section is required as with 3D Processor the specification of the export format takes place within the configuration settings file itself.
Conversion Script (BETA)
The conversion script is able to batch convert RapidCompact CLI commands and JSON settings files into 3D Processor CLI commands and JSON settings files. The script is python based.
Link to GitHub Repo Coming Soon ✨✨✨
Current Limitations
RapidCompact Commands (converted input):
| Command | Description | Support Status |
|---|---|---|
| -i [ --import ] | imports an asset from a file | ✅ |
| -e [ --export ] | exports an asset to a file | ✅ |
| -p [ --print_info ] | prints information about the current 3D asset | ✅ |
| -c [ --compact ] | turns the current asset into a simplified, textured representation | ✅ |
| -s [ --set ] | sets the setting with the given name to the given value | ✅ |
| --read_config | reads and apply the given config file | ✅ |
| --write_config | writes current settings to the given config file | ✅ |
| --write_info | writes information about the current 3D asset to a JSON file | ✅ |
| --write_metrics | writes metrics to a file using this ID | ✅ |
| --render_image | renders an image of the current asset to a file | ✅ |
| --render_turntable | renders a turntable-like image series to a directory | ✅ |
| --pop | removes the current 3D asset from the stack | ✨ |
| --remove_invisible_geometry | removes geometry that cannot be seen from the asset | ❌ |
| --remove_small_features | removes lumps of geometry [...] | ❌ |
| --remove_duplicate_vertices | removes duplicated vertices from the asset | ❌ |
| -g [ --get ] | gets the value of the given setting and prints it | ❌ |
| --duplicate | duplicates the current 3D asset on the stack | ❌ |
| --scale | scales the current 3D asset on the stack using units relative to the asset | ❌ |
| --flatten | flattens (combining meshes and transformations) the 3D asset at the top of the stack | ❌ |
| --export_web | exports to a directory with HTML 3D viewer | ❌ |
Future Updates
A minor update of 3D Processor CLI v7.x which supports the direct ingestion and conversion of most legacy RapidCompact (v1-6) JSON configuration settings files is scheduled.