Open CAD Module

Supported Functions:

extract

Summary

The Open CAD Module provides comprehensive CAD data extraction from open CAD file formats (STEP, IGES) and FreeCAD native files (FCStd) using FreeCAD, an open-source CAD application. This integration enables users to extract geometry, assembly data, geometric properties, parameters, and metadata from industry-standard neutral CAD formats.

Supported File Types: .step, .stp, .iges, .igs, .fcstd

Connection Methods: Upload

Example Files

Test the Open CAD extraction with this sample FreeCAD file:

• Download Example FreeCAD Model: cube_sphere.FCStd

How and Where to Use

You can use the Open CAD Module through either the Istari Digital Platform UI or the Istari Digital SDK. Both methods allow you to upload CAD files and extract comprehensive data including geometry, assembly structure, geometric properties, and metadata.

What You Can Do

The Open CAD Module enables you to:

• Extract 3D geometry as OBJ files for visualization and downstream processing
• Extract assembly structure and hierarchy information (JSON)
• Extract geometric properties including volume, surface area, center of mass, and bounding box (JSON)
• Extract parametric data and features from FreeCAD native files (FCStd) (JSON)
• Generate metadata reports with complete extraction summaries and file information (JSON)
• Generate rendered component visualizations from 7 standard engineering views (directory)
• Extract GD&T annotations (JSON, future enhancement)

Prerequisites

Before using this integration, ensure:

• FreeCAD 1.0+ is installed and configured by your administrator
• You have access to the Istari Digital Platform UI or the Istari Digital SDK
• The Open CAD Module is installed on the Istari Digital Agent
• The cad-geometry-toolkit is bundled with the module (automatically included during build)

API

Functions

Function	Description	Inputs	Outputs
@istari:extract	Extracts comprehensive CAD data from open formats (STEP, IGES) and FreeCAD native files (FCStd)	.step, .stp, .iges, .igs, .fcstd	geometry_obj, assembly_data, geometric_properties, parameters_data (FCStd only), gdt_data, metadata_report, views

Output Examples

Artifact Name	Type	Description
geometry_obj	File (OBJ)	3D geometry exported as OBJ file format for visualization and downstream processing
assembly_data	File (JSON)	Assembly structure and hierarchy information
geometric_properties	File (JSON)	Volume, surface area, center of mass, bounding box, and other geometric measurements
parameters_data	File (JSON)	Parametric data and features (available for FCStd files only)
gdt_data	File (JSON)	GD&T annotations (future enhancement)
metadata_report	File (JSON)	Complete extraction summary and file information
views	Directory	Rendered component visualizations from 7 standard engineering views (top, bottom, front, back, left, right, isometric)

Usage

Method 1: Upload

Upload your CAD files directly to the Istari Digital Platform and run extraction jobs using either the Platform UI or the SDK.

Using the Istari Digital Platform UI

Follow these steps to extract data from CAD files using the web interface:

1. Navigate to the Files page.
   Click the Files option in the left-hand sidebar of the Istari Digital Platform.

2. Upload your CAD file.
   Drag and drop your CAD file (.step, .stp, .iges, .igs, or .fcstd) into the Upload Files area, or click the Upload Files area to select a file from your computer. Wait for the upload to complete.

3. Open the model file.
   In the All Models tab, find and click the CAD file you just uploaded.

4. Go to the Artifacts tab.
   Click the Artifacts tab in the model viewer. This tab includes the function execution dialog where you can run data extraction.

5. Fill out the function execution form.
   The function interface includes the following fields:

   • Tool Name – Select freecad from the dropdown
   • Version – Select the FreeCAD version (e.g., 1.0.2)
   • Operating System – Select the environment where the function will execute (e.g., Windows 11, Ubuntu 22.04, Windows Server 2019)
   • Function – Select @istari:extract from the dropdown
   • Agent (optional) – Either select an agent manually or choose Select Agent for Me to let the system choose automatically

6. Run the extraction function.
   Once the form is complete, click the execution button to initiate extraction. The system will begin processing the function asynchronously.

7. Monitor the progress of the job.
   Click the Job Log tab to view all jobs submitted for this model. The job you just created will appear at the top of the list. The Status column will update live, starting in Pending and progressing towards Completed.

8. View the extraction results.
   When execution completes, navigate back to the Artifacts tab. You will see all generated artifacts listed, including:

   • geometry_obj – 3D geometry file (OBJ format)
   • assembly_data – Assembly structure (JSON)
   • geometric_properties – Geometric measurements (JSON)
   • parameters_data – Parametric data (JSON, FCStd files only)
   • metadata_report – Extraction summary (JSON)
   • views – Rendered views directory (for complex models)

9. Download or view artifacts.
   Click on any artifact name to view its contents, or use the download option to save it to your local machine.

Using the Istari Digital SDK

Prerequisite: Install Istari Digital SDK and initialize Istari Digital Client per instructions here

Step 1: Upload and Extract the File(s)

Upload the file as a model

# Upload CAD model (supports .step, .stp, .iges, .igs, .fcstd)
model = client.add_model(
    path="model.step",  # Can also use: .stp, .iges, .igs, or .fcstd files
    description="CAD model",
    display_name="My CAD Model",
)
print(f"Uploaded base model with ID {model.id}")

Extract once you have the model ID

extraction_job = client.add_job(
    model_id=model.id,
    function="@istari:extract",
    tool_name="freecad",
    tool_version="1.0.2",
    operating_system="Windows 11",  # Or: Ubuntu 22.04, Windows 10, Windows Server 2019, Windows Server 2022
)
print(f"Extraction started for model ID {model.id}, job ID: {extraction_job.id}")

Please choose appropriate tool_version and operating_system for your installation of FreeCAD.
Above is an example of how to call the function

Step 2: Check the Job Status

extraction_job.poll_job()

Step 3: Retrieve Results

Example

for artifact in model.artifacts:
    output_file_path = f"c:\\extracts\\{artifact.name}"

    if artifact.extension in ["txt", "csv", "md", "json", "html"]:
        with open(output_file_path, "w") as f:
            f.write(artifact.read_text())
    else:
        with open(output_file_path, "wb") as f:
            f.write(artifact.read_bytes())

Notes on File Types

• STEP files (.step, .stp): Extract geometry, assembly data, geometric properties, and metadata
• IGES files (.iges, .igs): Extract geometry, assembly data, geometric properties, and metadata
• FreeCAD native files (.fcstd): Extract all data types including parameters_data (parametric information not available in STEP/IGES formats)

Installation

Prerequisites

Before installing the Open CAD Module, ensure:

• FreeCAD 1.0+ is installed on the machine where the Istari Digital Agent runs
  • Windows: Download from FreeCAD.org
  • Default installation path: C:\Program Files\FreeCAD 1.0\
  • The module will auto-detect FreeCAD installation
• Istari Digital Agent version 9.0.0 or higher is installed

Configuration

Centralized Configuration

The Istari Agent is configured via the file istari_digital_config.yaml. The Agent expects the file to be located at:

• %LOCALAPPDATA%\istari_digital\ on Windows
• ~/.config/istari_digital/ on RHEL/Ubuntu

Configure the Open CAD Module using the istari_digital_agent_module_configurations section. The agent will pass this centralized configuration to the module:

agent:
  istari_digital_agent_module_configurations:
    "@istari:open_cad_module":
      "open_cad_freecad_installation_dir": "C:\\Program Files\\FreeCAD 1.0" # optional, set to null for auto-detection

Configuration Parameters

Parameter	Type	Required	Description
open_cad_log_level	String	No	Logging level (debug, info, warning, error, critical). Default: info
open_cad_log_file_path	String	No	Path to the log file. Default: open_cad_module.log
open_cad_freecad_installation_dir	String or null	No	Custom FreeCAD installation directory. Set to null for auto-detection (recommended). Example: "C:\\Program Files\\FreeCAD 1.0"

Custom FreeCAD Installation Path

If FreeCAD is installed in a non-standard location, configure it explicitly:

agent:
  istari_digital_agent_module_configurations:
    "@istari:open_cad_module":
      "open_cad_freecad_installation_dir": "C:\\MyApps\\FreeCAD"

Note: The module will look for python.exe (Windows) or python3 (Linux) in {open_cad_freecad_installation_dir}/bin/.

License Configuration

No license configuration is required. FreeCAD is open-source software and does not require license management.

Versions

Compatibility Notes

• FreeCAD Version: Requires FreeCAD 1.0 or higher
• Supported Operating Systems:
  • Ubuntu 22.04
  • Windows 10
  • Windows 11
  • Windows Server 2019
  • Windows Server 2022
• Istari Digital Agent: Requires version 9.0.0 or higher
• File Format Support:
  • STEP files (.step, .stp)
  • IGES files (.iges, .igs)
  • FreeCAD native files (.fcstd)

Changelog

Module Version 1.1.0

• Initial release of Open CAD Module
• Support for STEP, IGES, and FreeCAD native file formats
• Comprehensive data extraction including geometry, assembly data, and geometric properties
• Parametric data extraction for FreeCAD native files
• Integrated rendering with 7 standard engineering views via bundled cad-geometry-toolkit
• Launcher architecture for reliable FreeCAD subprocess execution
• Auto-detection of FreeCAD installation with optional custom path configuration

Release Notes

Key Changes Between Versions

Version 1.1.0 (Initial Release)

• Comprehensive CAD data extraction from open formats (STEP, IGES, FCStd)
• Geometry export as OBJ files
• Assembly structure and hierarchy extraction
• Geometric properties calculation (volume, surface area, center of mass, bounding box)
• Parametric data extraction for FreeCAD native files
• Metadata report generation
• Rendered views from 7 standard engineering perspectives
• Launcher architecture for reliable FreeCAD integration
• Support for both Windows and Linux operating systems

Troubleshooting

Common Issues

Issue: FreeCAD Not Found

• Symptom: Extraction jobs fail with "FreeCAD launcher not available" error
• Cause: FreeCAD is not installed or not detectable by the module
• Solution:
  1. Verify FreeCAD 1.0+ is installed on the machine running the Istari Digital Agent
  2. Check the default installation path: C:\Program Files\FreeCAD 1.0\ (Windows)
  3. If FreeCAD is installed in a custom location, configure open_cad_freecad_installation_dir in module_config.json
  4. Verify the module can find python.exe (Windows) or python3 (Linux) in the FreeCAD installation directory

Issue: Missing Artifacts

• Symptom: Some expected artifacts are not generated (e.g., parameters_data for STEP files)
• Cause: Certain artifacts are only available for specific file types
• Solution:
  1. parameters_data is only available for FreeCAD native files (.fcstd), not for STEP or IGES files
  2. views directory requires the bundled cad-geometry-toolkit to be present
  3. Verify the input file format is supported (.step, .stp, .iges, .igs, .fcstd)
  4. Check module logs for processing errors

Issue: Extraction Fails with Processing Errors

• Symptom: Extraction job completes but fails during CAD processing
• Cause: File format issues, corrupted files, or FreeCAD processing errors
• Solution:
  1. Verify the input CAD file is not corrupted and can be opened in FreeCAD
  2. Check the module log file for detailed error messages
  3. Ensure the file format is supported (STEP, IGES, or FCStd)
  4. For complex assemblies, verify all referenced files are present (if applicable)

Issue: Views Directory Not Generated

• Symptom: The views directory artifact is missing from extraction results
• Cause: The cad-geometry-toolkit bundled with the module may not be accessible or the module installation may be incomplete
• Solution:
  1. Verify the module was installed correctly and all bundled files are present
  2. Check the module log file for errors related to the cad-geometry-toolkit
  3. Ensure the module has proper execution permissions
  4. Contact Istari Digital support if the issue persists

Getting Help

1. For general Agent and Software Troubleshooting Click Here
2. Check the module log file for detailed error messages (configured via open_cad_log_file_path)
3. Verify FreeCAD installation and accessibility
4. Review the module manifest and configuration parameters
5. Contact Istari Digital support for additional assistance

Tips and Best Practices

CAD File Preparation

• STEP Files: Ensure STEP files are exported with geometry data included. Some exporters may produce incomplete files.
• IGES Files: IGES files should be in a supported version. Verify file integrity before uploading.
• FreeCAD Native Files: For parametric data extraction, use FreeCAD native files (.fcstd). Parameters defined in FreeCAD will be extracted.
• Assemblies: For complex assemblies, ensure all referenced components are included or accessible.

Performance Optimization

• Large CAD files may take longer to process. Monitor job status and logs for progress.
• The launcher architecture isolates FreeCAD processing, providing reliability and compatibility.
• Geometry rendering (views) may take additional time for complex models.

Digital Thread Integration

• Extracted geometry_obj files can be used for visualization and downstream geometric analysis
• assembly_data provides structured information for digital thread workflows
• geometric_properties enable automated property calculations and comparisons
• parameters_data from FCStd files enables parametric digital thread workflows

FAQ

• Why is parameters_data only available for FCStd files?

  • Parametric data is specific to FreeCAD's native format. STEP and IGES are neutral formats that don't preserve parametric information.

• Can I extract data from CATIA or SolidWorks files directly?

  • Not directly. You would need to export your models to STEP or IGES format first, then use this module for extraction.

• Can I customize the FreeCAD installation path?

  • Yes, set open_cad_freecad_installation_dir in the centralized configuration (istari_digital_config.yaml) to specify a custom path. Set to null for auto-detection.