General Material Information

Before you begin the walkthrough, read through the following section for a better understanding of the Material class.

All Material objects can be retrieved using a Material class filter. Material objects are also available in Document, Category, Element, Face, and so on, and are discussed in the pertinent sections in this chapter. Wherever you get a material object, it is represented as the Material class.

Properties

A material will have one or more aspects pertaining to rendering appearance, structure, or other major material category. Each aspect is represented by properties on the Material class itself or via one of its assets, structural or thermal. The StructuralAsset class represents the properties of a material pertinent to structural analysis. The ThermalAsset class represents the properties of a material pertinent to energy analysis.

Code Region 19-3: Getting material properties

private void ReadMaterialProps(Document document, Material material)
{
    ElementId strucAssetId = material.StructuralAssetId;
    if (strucAssetId != ElementId.InvalidElementId)
    {
        PropertySetElement pse = document.GetElement(strucAssetId) asPropertySetElement;
        if (pse != null)
        {
            StructuralAsset asset = pse.GetStructuralAsset();

            // Check the material behavior and only read if Isotropic
            if (asset.Behavior == StructuralBehavior.Isotropic)
            {
                // Get the class of material
                StructuralAssetClass assetClass = asset.StructuralAssetClass; // Get other material properties

                // Get other material properties
                double poisson = asset.PoissonRatio.X;
                double youngMod = asset.YoungModulus.X;
                double thermCoeff = asset.ThermalExpansionCoefficient.X;
                double unitweight = asset.Density;
                double shearMod = asset.ShearModulus.X;
                double dampingRatio = asset.DampingRatio;
                if (assetClass == StructuralAssetClass.Metal)
                {
                    double dMinStress = asset.MinimumYieldStress;
                }
                elseif (assetClass == StructuralAssetClass.Concrete)
                {
                    double dConcComp = asset.ConcreteCompression;
                }
            }
        }
    }
}

Classification

The material classification relevant to structural analysis (i.e. steel, concrete, wood) can be obtained from the StructuralAssetClass property of the StructuralAsset associated with the material.

Note: The API does not provide access to the values of Concrete Type for Concrete material.

The material classification relevant to energy analysis (i.e. solid, liquid, gas) can be obtained from the ThermalMaterialType property of the ThermalAsset associated with the material.

Other Properties

The material object properties identify a specific type of material including color, fill pattern, and more.

Properties and Parameter

Some Material properties are only available as a Parameter. A few, such as Color, are available as a property or as a Parameter using the BuiltInParameter MATERIAL_PARAM_COLOR.

Rendering Information

Collections of rendering data are organized into objects called Assets, which are read-only. You can obtain all available Appearance-related assets from the Application.Assets property. An appearance asset can be accessed from a material via the Material.AppearanceAssetId property.

The following figure shows the Appearance Library section of the Asset Browser dialog box, which shows how some rendering assets are displayed in the UI.

Figure 106: Appearance Library

The Materials sample application included with the SDK shows how to set the RenderApperance property to a material selected in a dialog. The dialog is populated with all the Asset objects in Application.Assets.

FillPattern

All FillPatterns in a document are available using a FilteredElementCollector filtering on class FillPatternElement. A FillPatternElement is an element that contains a FillPattern while the FillPattern class provides access to the pattern name and the set of FillGrids that make up the pattern.

There are two kinds of FillPatterns: Drafting and Model. In the UI, you can only set Drafting fill patterns to Material.CutPatternId. The fill pattern type is exposed via the FillPattern.Target property. The following example shows how to change the material FillPattern.

Code Region 19-4: Setting the fill pattern

public void SetFillPattern(Document document, Material material)
{
    FilteredElementCollector collector = new FilteredElementCollector(document);
    ICollection<ElementId> fillPatternElements = collector.OfClass(typeof(FillPatternElement)).ToElementIds();
    foreach (ElementId fillPatternId in fillPatternElements)
    {
        // always set successfully
        material.CutPatternId = fillPatternId;
        material.SurfacePatternId = fillPatternId;
    }
}