Material Workbench/pt-br

Other languages:
Inspection Workbench
Mesh Workbench
Index
Material workbench icon

Introdução

introduced in 1.0

The Material Workbench handles the FreeCAD material system.

Ferramentas

  • Edit: Opens the Material Editor.

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:

  • Material: Assigns a material to selected objects.
  • Appearance: Sets the display properties of selected objects. Often used after applying a material, when a given material does not define appearance properties.

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

  • Usage: Click the Edit button in the Material Workbench.
  • Purpose: The Material Editor is a tool for defining and managing materials. Its sole function is to create new materials, edit the properties of existing ones, and organize them.
  • Behavior:
    • It is disconnected from your 3D model; selecting an object in your document has no effect on the editor.
    • You cannot assign a material to an object from this window. Clicking OK simply closes the editor.

Material Selector

  • Usage: Select one or more objects in the 3D View or Tree View, then select the Material option from the context menu.
  • Purpose: This tool is used to assign a material to objects.
  • Behavior:
    • It opens a task panel containing a material browser tree.
    • The Launch Editor button launches the Material Editor to edit or create a material.
    • Selecting a material in the material browser tree immediately applies its properties to the selected objects. This is the required step to link a material's physical data to a part.

Physical vs. appearance properties

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

  • Physical properties: These define the engineering characteristics of a material, which are used for calculations and simulations (e.g., in the FEM Workbench). Examples include Density, YoungsModulus, and PoissonRatio.
  • Appearance properties: These define the visual look of a material for rendering purposes. Examples include DiffuseColor, Shininess, and Transparency.

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.

  • How to override: Select the Appearance option from the object's Tree View or 3D View context menu. Any changes you make here will take precedence over the appearance properties of the assigned material.
    • Caveats: This can be a source of confusion. If you have assigned a material to an object but its color doesn't change, it is likely because the object has a local appearance override. There is no clear visual indicator in the UI to show that an override is active.
  • How to revert an override: To restore the material's appearance, you can use the Appearance tool again and re-select the material to have its appearance properties applied.

Properties

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

  • DadosShape Material: This is the most important property. It is added to the Document Object. It holds a link to a full Materials::Material object, giving access to all its physical and appearance data for calculations and scripting. This is a hidden property.
  • VistaShape Appearance: This property exists on the object's View Provider. It is a list that controls the final rendering of the object in the 3D View and is what gets modified when you use the Appearance task panel.

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.

  • ❌ Incorrect method (returns text): Using the PhysicalProperties dictionary returns a string with units, which cannot be used in subsequent formulas.
=<<MyBody>>.ShapeMaterial.PhysicalProperties[<<Density>>]
→ Returns "7850 kg/m^3"
  • ✅ Correct method (returns a Quantity): Using the PropertyObjects dictionary and accessing its Value attribute returns a full Quantity object that can be used directly in calculations.
=<<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