Material Workbench

Other languages:
Inspection Workbench
Mesh Workbench
Index
Material workbench icon

Introduction

introduced in 1.0

The Material Workbench handles the FreeCAD material system.

Tools

All Material Workbench tools can be accessed from the Material menu. Almost all are also available in the Material toolbar.

Related Tools

While not provided by the Material workbench, these Material-related tools are included in FreeCAD's core and can be used without loading the workbench:

Preferences

Working with Materials in FreeCAD

This guide explains the core concepts and workflows for using the Material system in FreeCAD. It covers the different tools, properties, and key technical details for both interactive and scripted use.

The Two Main Tools: Editor vs. Selector

There are two primary interfaces for the material workflow, which serve separate and distinct purposes.

The Material Editor (The Library Manager)

The Material Selector (The Context Menu Setter)

Physical vs. Appearance Properties

A material in FreeCAD is defined by two distinct sets of properties:

A material is not required to have both. Some materials might be defined only for analysis (with only physical properties), while others might be defined only for visualization (with only appearance properties).

Overriding Material Appearance

An object's final appearance is determined by a hierarchy. The visual properties set in a material can be overridden by local settings on the object itself.

Behind the Scenes: Hidden Properties

When you assign a material, FreeCAD links the data to the object and its view provider using hidden properties. You will not see these in the default DataData tab of the Property View.

Accessing Material Properties

Disconnect Between Shape and Material

Assigning a material does not change an object's geometric properties. A Part::Box with DataLength = 10mm will remain 10mm long whether its material is Steel or ABS. Physical characteristics like mass are not stored as persistent properties on the object; they are calculated on-demand by other tools (like macros or the FEM Workbench) by reading both the object's geometry (Data.Shape.Volume) and its material data (DataShapeMaterial).

Using Expressions (Spreadsheet Example)

You can access material property values dynamically using expressions, which is particularly powerful in the Spreadsheet Workbench. To ensure you get a usable numerical quantity instead of a text string, you must use the PropertyObjects dictionary.

If this value is in cell A1 of your spreadsheet, you can then write a formula in cell A2 like =A1 * 10, and it will work correctly.

Scripting with Materials

You can get and set material properties using Python scripting. The primary methods are .getPhysicalValue() and .setPhysicalValue(). 

import FreeCAD
import FreeCADGui

# Get a reference to your object (e.g., a PartDesign Body)
obj = App.ActiveDocument.getObject("Body")

# --- Check for and Get a Property ---
if obj.ShapeMaterial.hasPhysicalProperty("Density"):
    
    # Get the value. This returns a FreeCAD.Quantity object.
    density_quantity = obj.ShapeMaterial.getPhysicalValue("Density")
    
    print(f"The material is: {obj.ShapeMaterial.Name}")
    print(f"The density is: {density_quantity}")
    print(f"Numerical value: {density_quantity.Value}")

else:
    print("The selected material does not have a 'Density' property.")


# --- Set a Property ---
# The value can be a string with units or a FreeCAD.Quantity object.
try:
    obj.ShapeMaterial.setPhysicalValue("Density", "8000 kg/m^3")
    App.ActiveDocument.recompute()
    print("Density successfully updated.")

except Exception as e:
    print(f"Failed to set property: {e}")
Inspection Workbench
Mesh Workbench
Index
User documentation