Geometric Matching

PCLI2 provides powerful geometric matching capabilities to find similar assets in your Physna tenant. This feature leverages advanced algorithms to identify assets with similar geometries, regardless of their orientation, scale, or position.

Table of Contents

Overview

Geometric matching helps you:

  • Find duplicate or near-duplicate assets
  • Identify variations of the same part
  • Locate similar components across different projects
  • Reduce storage costs by identifying redundant assets
  • Improve design workflows by finding existing similar parts

Geometric matching serves as the foundation for other powerful capabilities:

  • Metadata Inference: Automatically propagate metadata from reference assets to geometrically similar assets using pcli2 asset metadata inference
  • Metadata Management: Create, update, retrieve, and delete metadata for assets using commands like pcli2 asset metadata create, pcli2 asset metadata get, and pcli2 asset metadata delete
  • Part Family Management: Organize and categorize groups of similar components
  • Design Optimization: Identify opportunities for part consolidation and standardization

Single Asset Matching

Find geometrically similar assets for a specific reference asset.

Basic Usage

# Find matches for a specific asset
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0

# Using asset UUID instead of path
pcli2 asset geometric-match --uuid 123e4567-e89b-12d3-a456-426614174000 --threshold 85.0

# Find matches with CSV output and headers
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers

# Find matches with CSV output, headers, and metadata
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers --metadata

Output Formats

JSON Format (Default)

[
  {
    "referenceAssetName": "ReferenceModel.stl",
    "candidateAssetName": "SimilarModel.stl",
    "matchPercentage": 95.75,
    "referenceAssetPath": "/Home/Folder/ReferenceModel.stl",
    "candidateAssetPath": "/Home/DifferentFolder/SimilarModel.stl",
    "referenceAssetUuid": "123e4567-e89b-12d3-a456-426614174000",
    "candidateAssetUuid": "987fc321-fedc-ba98-7654-43210fedcba9"
  }
]

CSV Format

REFERENCE_ASSET_NAME,CANDIDATE_ASSET_NAME,MATCH_PERCENTAGE,REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
ReferenceModel.stl,SimilarModel.stl,95.75,/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75

CSV Format with Metadata

When using the --metadata flag, the output includes metadata fields from both the reference and candidate assets. This produces CSV output with additional metadata columns prefixed with REF_ for reference asset metadata and CAN_ for candidate asset metadata. The output also includes a COMPARISON_URL column that provides a link to view the comparison in the Physna UI:

REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL,REF_MATERIAL,CAN_MATERIAL,REF_COLOR,CAN_COLOR
/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,95.75,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75,Steel,Aluminum,Red,Blue

All metadata fields from all matched assets are included as columns, with empty values for assets that don't have a particular metadata field.

Complete Examples

Here are complete examples showing the command with and without the --metadata flag:

Without metadata:

pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers

Output:

REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,95.75,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75

With metadata:

pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers --metadata

Output:

REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL,REF_MATERIAL,CAN_MATERIAL,REF_COLOR,CAN_COLOR
/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,95.75,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75,Steel,Aluminum,Red,Blue

Threshold Settings

The threshold parameter controls the minimum similarity percentage required for a match:

  • 0.0 - Return all possible matches (may include unrelated assets)
  • 50.0 - Very loose matching (many potential matches)
  • 80.0 - Default setting (good balance of accuracy and recall)
  • 90.0 - Strict matching (high confidence matches)
  • 95.0+ - Very strict matching (near duplicates only)

Folder-Based Matching

Find geometrically similar assets for all assets in a specified folder. This command processes assets in parallel for improved performance.

Basic Usage

# Find matches for all assets in a folder
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 85.0

Including Subfolders

By default only the assets sitting directly in the named folder are matched. A folder that holds nothing but subfolders therefore produces no report:

# /Creo Files contains 8 subfolders and no assets of its own
pcli2 folder geometric-match --folder-path "/Creo Files" --threshold 85.0
# ❌ Error: No assets found directly in the specified folder(s)
#    1. The folder(s) contain 8 subfolder(s) - pass --recursive to include the assets in them

Pass --recursive (-R) to walk the whole subtree:

# Matches every asset under /Creo Files, including all of its subfolders
pcli2 folder geometric-match --folder-path "/Creo Files" --threshold 85.0 --recursive

--recursive can widen the scope dramatically — a folder with one asset of its own may have thousands underneath it, and each one costs a search. Raise --concurrent (up to 10) to speed it up, or name a deeper folder to narrow the scope.

The same flag is available on folder part-match and folder visual-match.

Comparison Viewer URL

Both geometric-match and folder geometric-match commands include a comparison URL in their output that allows you to view the geometric match in the Physna UI. The URL is available in both JSON and CSV formats:

  • JSON: The field is named comparisonUrl
  • CSV: The column is named COMPARISON_URL

The URL follows this format:

https://app.physna.com/tenants/{tenant_short_name}/compare?asset1Id={reference_asset_uuid}&asset2Id={candidate_asset_uuid}&tenant1Id={tenant_uuid}&tenant2Id={tenant_uuid}&searchType=geometric&matchPercentage={match_percentage}

Excel (XLSX) Output

In addition to json and csv, the folder match command supports --format xls, which writes a color-highlighted Excel workbook designed for a human reader. It contains exactly the same columns, in the same order, as the CSV output (always including the REF_/CAN_ metadata pairs), rendered with visual aids that make a large report easy to scan:

  • Frozen headers and identity columns — the two header rows and the leading reference path, candidate path, and match-percentage columns stay in view while you scroll a wide, tall report.
  • Grouped metadata pairs — each REF_<field>/CAN_<field> pair is boxed and labeled once with the field name (e.g. MATERIAL over a REF and a CAN sub-column), so the reference/candidate pairs stand out among the plain columns.
  • Metadata diff highlighting — for every pair, both cells are shaded: 🟩 green when the two values match, 🟥 red when they differ, and 🟨 amber when a value is present on only one side.
  • Match-score heat map — the MATCH_PERCENTAGE column is shaded on a gradient (cool at 0%, through yellow at 50%, to red-hot at 100%) and the rows are sorted by match percentage, highest first.
  • Clickable comparison links — COMPARISON_URL is the last column (its long value is rarely read, so the metadata columns come before it), written as a hyperlink you can click to open the side-by-side comparison in a browser.

Because Excel is a binary format, xls writes to a file rather than standard output. Use --output (or -o) to choose the path; if omitted, the workbook is written to match_report.xlsx in the current directory. The extension is always normalized to .xlsx (the modern Office Open XML format); if it had to be changed, a warning is printed to stderr. On success the command follows the UNIX convention of printing nothing to stdout.

# Write a highlighted Excel report for a folder
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 80.0 --format xls --output report.xlsx

# Multiple folders, default output filename (match_report.xlsx)
pcli2 folder geometric-match --folder-path /Home/FolderA/ --folder-path /Home/FolderB/ --format xls

The xls format always includes metadata (the metadata diff is its whole point), so the --metadata flag is implied and does not need to be passed.

Performance Options

Concurrency Control

Control how many simultaneous operations are performed (range: 1-10, default: 1):

# Use 8 concurrent operations (default is 1, maximum is 10)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 8

# Use the default (1 concurrent operation)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/

# Invalid values will cause the command to fail
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 15
# This will show an error: "Invalid value for '--concurrent': must be between 1 and 10, got 15"

Progress Tracking

Display progress information during long-running operations:

# Show progress information
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --progress

# Combine with concurrency to show multiple progress bars (one per concurrent operation)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 8 --progress

When using both --concurrent and --progress flags together, the command will display:

  • An overall progress bar showing the total completion percentage
  • Individual progress bars for each concurrent operation showing which assets are being processed
  • Status messages indicating the current stage of each operation (starting search, processing matches, completion)

With --recursive, --progress also covers the folder scan that happens before any matching starts. A deep tree costs one API call per folder, so this phase can run for a while on its own:

⠹ Scanning /Creo Files: 46/312 folders, 1174 assets found

followed by a summary once the scan completes:

Scanned 1 folder path(s), found 3182 asset(s) to match

All of this goes to stderr, so piping stdout to a file or another command is unaffected. Without --progress the scan is silent.

Performance Options

Concurrency and Progress Combined

For optimal performance monitoring, combine both options:

# Use 10 concurrent operations with detailed progress tracking
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 10 --progress

# Combine with other options
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 85.0 --concurrent 8 --progress

Resuming an Interrupted Run

A match over a large tenant can run for hours, and until the report is written nothing has been saved. --checkpoint FILE changes that: every asset's result is appended to FILE the moment its search finishes, and re-running the same command with the same file reuses what was recorded and searches only the assets that are left.

# First attempt - interrupted after two hours
pcli2 folder geometric-match --folder-path "/Creo Files" --recursive \
  --threshold 85 --concurrent 8 --progress \
  --checkpoint creo-match.jsonl --format csv --headers > creo-matches.csv

# Same command again: picks up where it stopped
pcli2 folder geometric-match --folder-path "/Creo Files" --recursive \
  --threshold 85 --concurrent 8 --progress \
  --checkpoint creo-match.jsonl --format csv --headers > creo-matches.csv

On the second run stderr reports what was reused:

Resuming from checkpoint 'creo-match.jsonl': 2,431 of 3,182 asset(s) already searched

Points worth knowing:

  • The file is tied to the exact run: search type, tenant, folder paths, --threshold, --recursive, --exclusive and (for visual search) --limit. A file written by a different combination is refused with a message naming the run it belongs to; delete it or pick another path.
  • Only successful searches are recorded. An asset whose search failed is searched again on the next run, which is also how a run that stopped on authentication failures is completed after pcli2 auth login.
  • The file is deleted once the report has been written successfully. It stays if the report fails - for example an Excel workbook too tall for a worksheet - so the same searches are not repeated after fixing the output options.
  • The output format is not part of the fingerprint: an interrupted CSV run can be finished as JSON or Excel.
  • Assets added to the folder between runs are searched; assets removed are dropped from the report.

part-match and visual-match take the same option.

Handling Large Folders

For folders with many assets, consider these strategies:

  1. Use a checkpoint: --checkpoint FILE makes an interruption cost minutes instead of hours
  2. Adjust threshold: Higher thresholds reduce processing time
  3. Increase concurrency: Use more concurrent operations (but watch resource usage)
  4. Process in batches: Break large folders into smaller subfolders

Direct Asset Similarity (Match Scores)

While geometric-match searches your tenant for assets similar to a single reference, asset similarity compares two specific assets and returns the pairwise match scores between them. Use it when you already know both assets you want to compare.

Each asset can be identified by either its UUID or its path — PCLI2 resolves paths to UUIDs automatically:

  • Reference (source) asset: --reference-uuid or --reference-path
  • Candidate (target) asset: --candidate-uuid or --candidate-path

Both assets must be 3D models in a finished state, and they must be different assets (comparing an asset with itself is rejected by the API).

Basic Usage

# Compare two assets by path
pcli2 asset similarity \
  --reference-path /Home/Folder/block1.stl \
  --candidate-path /Home/Folder/block2.stl

# Mix identifiers: reference by UUID, candidate by path
pcli2 asset similarity \
  --reference-uuid 123e4567-e89b-12d3-a456-426614174000 \
  --candidate-path /Home/Folder/block2.stl

# CSV output with headers
pcli2 asset similarity \
  --reference-path /Home/Folder/block1.stl \
  --candidate-path /Home/Folder/block2.stl \
  --format csv --headers

The command is also available under the alias pcli2 asset match-scores.

Output Formats

JSON Format (Default)

{
  "referenceAssetPath": "/Home/Folder/block1.stl",
  "referenceAssetUuid": "123e4567-e89b-12d3-a456-426614174000",
  "candidateAssetPath": "/Home/Folder/block2.stl",
  "candidateAssetUuid": "987fc321-fedc-ba98-7654-43210fedcba9",
  "geometric": {
    "matchPercentage": 90.21,
    "forwardMatchPercentage": 86.58,
    "reverseMatchPercentage": 86.58
  },
  "comparisonUrl": "https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=tenant-uuid&tenant2Id=tenant-uuid&searchType=geometric&matchPercentage=90.21"
}

The geometric scores describe how similar the two models are:

  • matchPercentage: Overall geometric similarity (100% = geometrically identical)
  • forwardMatchPercentage: How much of the reference asset's geometry exists in the candidate
  • reverseMatchPercentage: How much of the candidate asset's geometry exists in the reference

A volumetric object (with its own matchPercentage) is included only when volumetric scoring is enabled for your tenant; otherwise it is omitted. Contact Physna sales to enable volumetric scoring.

CSV Format

REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,FORWARD_MATCH_PERCENTAGE,REVERSE_MATCH_PERCENTAGE,VOLUMETRIC_MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
/Home/Folder/block1.stl,/Home/Folder/block2.stl,90.21,86.58,86.58,,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=tenant-uuid&tenant2Id=tenant-uuid&searchType=geometric&matchPercentage=90.21

The VOLUMETRIC_MATCH_PERCENTAGE column is empty unless volumetric scoring is enabled for your tenant.

Error Handling

Common Errors

HTTP 409 Conflict

A 409 from the search endpoint means the asset cannot be searched in its current state: it is still indexing, has no 3D data, or failed to index. This is a property of the tenant, not of the run, so the asset is counted as "not searchable" in the summary and the run continues; it is not retried. Transient failures (connection errors, 408/429/502/503/504) are retried with backoff, and a 401/403 triggers one token renewal and retry. A run that loses more than 10% of its searches to operational failures, or that is stopped by repeated authentication failures, exits 69 rather than producing a report that looks complete.

Permission Denied

When you don't have permission to perform geometric search:

ERROR: Error: Access forbidden. You don't have permission to perform geometric search on this asset.

Check your tenant permissions and API credentials.

Asset Not Found

When the specified asset or folder cannot be found:

ERROR: The asset with ID 'XXX' cannot be found in tenant 'YYY'

Verify the asset path or UUID is correct.

Best Practices

Optimizing Performance

  1. Use appropriate thresholds: Start with 80-85% and adjust based on results
  2. Limit search scope: Use specific folders rather than searching entire tenants
  3. Monitor resource usage: Adjust concurrency based on your system capabilities
  4. Use progress tracking: Monitor long-running operations

Interpreting Results

  • High match percentages (>95%): Likely duplicates or very similar assets
  • Medium match percentages (80-95%): Similar geometry with variations
  • Low match percentages (<80%): May be false positives or loosely related

Automation Tips

  1. Schedule regular deduplication: Run geometric matching periodically to identify duplicates
  2. Integrate with CI/CD: Use geometric matching in automated workflows
  3. Export results: Use CSV format for easy analysis in spreadsheets

Advanced Usage

Scripting Examples

Bash Script for Regular Deduplication

#!/bin/bash
# deduplicate.sh

FOLDERS=("/Home/ProjectA/" "/Home/ProjectB/" "/Home/Archive/")
THRESHOLD=95.0
CONCURRENT=8  # Number of concurrent operations
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

for folder in "${FOLDERS[@]}"; do
    echo "Processing folder: $folder"
    pcli2 folder geometric-match \
        --folder-path "$folder" \
        --threshold $THRESHOLD \
        --concurrent $CONCURRENT \
        --format csv \
        --progress \
        > "duplicates_${folder//\//_}_$TIMESTAMP.csv"
done

echo "Deduplication complete. Results saved to CSV files."

PowerShell Script for Windows

# deduplicate.ps1

$Folders = @("/Home/ProjectA/", "/Home/ProjectB/", "/Home/Archive/")
$Threshold = 95.0
$Concurrent = 8  # Number of concurrent operations
$Timestamp = Get-Date -Format "yyyyMMdd_HHmmss"

foreach ($folder in $Folders) {
    Write-Host "Processing folder: $folder"
    pcli2 folder geometric-match `
        --folder-path $folder `
        --threshold $Threshold `
        --concurrent $Concurrent `
        --format csv `
        --progress `
        > "duplicates_$($folder.Replace('/', '_'))_$Timestamp.csv"
}

Write-Host "Deduplication complete. Results saved to CSV files."

Troubleshooting

Performance Issues

If matching operations are taking too long:

  1. Reduce concurrency: Lower the --concurrent value
  2. Increase threshold: Use higher threshold values to reduce matches
  3. Check network: Ensure good connectivity to the Physna API
  4. Monitor server status: Check if the Physna service is experiencing issues

Incomplete Results

If you're not seeing expected matches:

  1. Lower threshold: Try lower threshold values
  2. Check asset types: Ensure assets are compatible geometric file types
  3. Verify permissions: Confirm you have access to all assets in the search scope
  4. Contact support: If issues persist, reach out to Physna support
  • asset geometric-match - Find matches for a single asset
  • folder geometric-match - Find matches for all assets in a folder
  • asset similarity - Get pairwise match scores between two specific assets (alias: asset match-scores)
  • asset list - List assets in a folder
  • asset get - Get detailed asset information

Use pcli2 asset geometric-match --help, pcli2 folder geometric-match --help, and pcli2 asset similarity --help for detailed command information.