Getting Started#

The volmdlr_tools package provides numerical methods for CAD analysis, building on top of volmdlr and dessia_common. It offers graph-based analysis, feature recognition, shape classification, and assembly analysis.

Installation#

Install from the root directory:

pip install -e .

For development with documentation and tests:

pip install -e .[doc,test]

Reconstruction lives in volmdlr_build>=0.9.0, imported from volmdlr_build.reconstruction.

Dependencies#

Core dependencies (installed automatically):

  • volmdlr>=0.18.2 - BRep geometry library

  • dessia_common>=0.18.0 - Serialization and platform integration

  • networkx - Graph algorithms

  • plot_data>=0.26.7 - Visualization

Tutorial Data Files#

Download

To follow the examples below, download the required data files:

Quick Examples#

Feature Recognition#

Extract blends (fillets) and cavities (holes) from a BRep shape:

from volmdlr.model import VolumeModel
from volmdlr_tools.features import FeatureProcessor

# Load a STEP file
model = VolumeModel.from_step("data/step/nist_ctc_02_asme1_nx1980_rc-ap242e3.stp")
shape = model.primitives[0]

# Extract features
processor = FeatureProcessor(shape=shape)
processor.extract_blends()
processor.extract_cavities()

# Access results: the processor owns every extracted feature
print(f"Found {len(processor.blends)} blends")
print(f"Found {len(processor.cavities)} cavities")

# A breakdown by concrete feature type
for feature_type, count in processor.get_feature_count().items():
    print(f"  {feature_type}: {count}")

To look at the result rather than count it, open it in the local viewer. This one is not executed by the test suite — it waits on a window — so it carries doc-only:

# Every feature type in its own color, alongside the part
processor.view()

On the platform, processor.show_features() returns the same scene as Babylon display data instead of opening a window.

Sheet Metal Recognition#

Recognize sheet metal parts and extract features:

from volmdlr.model import VolumeModel
from volmdlr_tools.features import FeatureProcessor

# Load and recognize
model = VolumeModel.from_step("data/step/lances-sheet-metal.step")
shape = model.primitives[0]

processor = FeatureProcessor(shape=shape)

# Sheet metal gets its own extraction: bends, corners, cutouts. A part that is
# not sheet metal is refused here rather than quietly returning nothing.
processor.extract_sheet_metal_features()

print(f"Thickness: {processor.sheet_metal.get_thickness():.3f}")
for feature_type, count in processor.get_feature_count().items():
    print(f"  - {feature_type}: {count}")
print(f"Bends: {len(processor.bends)}")

The same FeatureProcessor handles both parts. Ask it processor.is_sheet_metal when you do not know what you were handed, or call extract_all(), which takes the sheet metal path on its own. Reach for SheetMetalRecognizer directly only when you want the classification (main faces versus thickness faces) without the features.

Assembly Analysis#

Analyze CAD assemblies with graph-based methods:

from volmdlr.model import VolumeModel
from volmdlr_tools.graph.assembly import GraphAssembly

# Load assembly
model = VolumeModel.from_step("data/step/Gearbox Assembly.STEP")

# Create assembly graph
graph = GraphAssembly.from_volume_model(model)

# Access components
for node in graph.get_nodes():
    print(f"Component: {graph[node]['name']}")

Shape Signatures#

Compare shapes using distribution signatures:

from volmdlr.model import VolumeModel
from volmdlr_tools.shapes.signatures.distributions import D2Signature

# Create signatures
model1 = VolumeModel.from_step("data/signatures_dataset/1.step")
model2 = VolumeModel.from_step("data/signatures_dataset/2.step")

sig1 = D2Signature.from_volume_model(model1, n_points=100000)
sig2 = D2Signature.from_volume_model(model2, n_points=100000)

# Compare
similarity = sig1.similarity(sig2)
print(f"Similarity: {similarity:.4f}")

Module Overview#

Graph Analysis#

  • volmdlr_tools.graph.core - Base Graph class with serialization

  • volmdlr_tools.graph.faces - AttributedAdjacencyGraph (AAG) for face adjacency

  • volmdlr_tools.graph.assembly - GraphAssembly for CAD assemblies

  • volmdlr_tools.graph.kinematics - Joint detection and determinacy analysis

Feature Recognition#

  • volmdlr_tools.features.core - FeatureProcessor orchestrator

  • volmdlr_tools.features.extractors - Blend, cavity, and sheet metal extractors

  • volmdlr_tools.features.feature_types - Feature abstractions

Shape Classification#

  • volmdlr_tools.shapes.recognizers - Shape recognizers (sheet metal, swept shapes)

  • volmdlr_tools.shapes.signatures - Shape signatures and distribution signatures

Distance Analysis#

  • volmdlr_tools.distance.clearance - Clearance distance computation

  • volmdlr_tools.distance.interference - Interference detection

Next Steps#