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

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

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.

Material tools

Material Editor

Material Selector

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).

Override 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.

Properties

When you assign a material, FreeCAD links the data to the object and its view provider using two properties.

Expressions

You can access material property values 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. 

=<<MyBody>>.ShapeMaterial.PhysicalProperties[<<Density>>]
→ Returns "7850 kg/m^3"
=<<MyBody>>.ShapeMaterial.PropertyObjects[<<Density>>].Value
→ Returns a Quantity object that the spreadsheet can use numerically.
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

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