Setting Material Render Appearance

Several queries concerning rendering issues were discussed recently and solved by the new Visual Materials API included in Revit 2018.1:

• Revit 2018.1 and the Visual Materials API
• Appearance Asset Editing SDK sample

Here comes another one, answered more completely by Boris Shafiro's Autodesk University class on this topic:

• AU class catalogue entry: SD124625 – New API to Modify Visual Appearance of Materials in Revit
• Class handout and slides: SD124625 – Visual Materials API

Question: How can I set the Material Render Appearance through the API in Revit 2018?

I can see there is the Autodesk.Revit.DB.Visual.Asset class, but how do I add to the list of Autodesk.Revit.DB.Visual.AssetProperty objects for a new material?

I noticed the forum thread on how to create or modify a rendering asset that seems to indicate limitations in this area...

Answer: Unfortunately, this is not possible in Revit 2018.

The good news is that it is possible in Revit 2018.1 using the Visual Materials API.

Check out Boris Shafiro's class at AU to learn about it.

SD124625 – Visual Materials API

The ability to use the Revit API to modify visual appearances of materials was among the top customer requests for years. This new API has been implemented in Revit 2018.1. This class presents the new Visual Materials API, coding workflows, and usage of multiple schemas for the visualization properties of materials in Revit software – by Boris Shafiro, Software Development Manager, Autodesk:

• Handout document PDF
• Slide deck PDF

For the sake of completeness and search engine findability, here is the pure text copied out of the slide deck:

• Learning Objectives
• The Basics
  • Materials API
  • Terminology
  • Material API building blocks
  • Visual Materials UI
• New Editing Capabilities in Materials API
  • Edit Scope
  • New Writable Properties
  • New Methods
  • Coding Workflow to Edit a Color
  • Connected Assets
  • Coding Workflow to Edit a Connected Asset
• Schemas and Property Names
  • Standard Material Schemas
  • Advanced Material Schemas
  • Common Schema
  • Schemas for Connected Assets
  • UnifiedBitmap
  • Property Names
  • Special Cases
• SDK Sample
  • AppearanceAssetEditing

Learning Objectives

Learn how to

• Use new API to modify visual appearance of Materials in Revit
• Navigate coding workflow to edit appearance assets
• Use multiple schemas for regular and advanced materials in Revit
• Write a sample plug-in for basic modification of the visual appearance of Revit materials

Materials API

• Basic Element Info (name, tags)
• Appearance properties
• Shaded view graphics
• Thermal & energy-related properties
• Physical & structural properties

Terminology

• Revit Material – An element representing a material, made of a collection of property sets
• Asset – The class representing a package of properties
• Appearance Asset – Asset representing visual material properties
• Appearance Asset Element – An element that stores an appearance asset
• Asset Property – One particular property of an asset

Material API building blocks

• Namespace Revit.DB Namespace Revit.DB.Visual
• Material – AppearanceAssetId
• AppearanceAssetElement – GetRenderingAsset()
• Asset – AssetProperty 1 ... AssetProperty N – [“name_string” ] or FindByName(name)
• AssetProperty – GetSingleConnectedAsset()

Visual Materials UI

Edit Scope

• AppearanceAssetEditScope
  • Start()
  • Commit()
  • Cancel()
• Contains one Asset (plus all connected Assets)

New Writable Properties

• AssetPropertyString.Value
• AssetPropertyBoolean.Value
• AssetPropertyInteger.Value
• AssetPropertyDouble.Value
• AssetPropertyFloat.Value
• AssetPropertyEnum.Value
• AssetPropertyDistance.Value (not always in feet)

New Methods

• AssetPropertyDoubleArray3d.SetValueAsXYZ()
• AssetPropertyDoubleArray4d.SetValueAsDoubles()
• AssetPropertyDoubleArray4d.SetValueAsColor()
• AssetPropertyList – add, insert, remove

Coding Workflow to Edit a Color

  using( AppearanceAssetEditScope editScope
    = new AppearanceAssetEditScope( document ) )
  {
    Asset editableAsset = editScope.Start( assetElem.Id );
    AssetPropertyDoubleArray4d genericDiffuseProperty
      = editableAsset["generic_diffuse"]
        as AssetPropertyDoubleArray4d;
    genericDiffuseProperty.SetValueAsColor( color );
    editScope.Commit( true );
  }

Connected Assets

• AssetProperty.GetSingleConnectedAsset()
• AssetProperty.RemoveConnectedAsset()
• AssetProperty.AddConnectedAsset( String schemaId )
• AssetProperty.AddCopyAsConnectedAsset( Asset renderingAsset )

Coding Workflow to Edit a Connected Asset

  using( AppearanceAssetEditScope editScope
    = new AppearanceAssetEditScope( document ) )
  {
    Asset editableAsset = editScope.Start( assetElem.Id );
    AssetProperty bumpMapProperty = editableAsset["generic_bump_map"];
    Asset connectedAsset = bumpMapProperty.GetSingleConnectedAsset();
    if( connectedAsset != null )
    {
      AssetPropertyString bumpmapBitmapProperty
        = connectedAsset["unifiedbitmap_Bitmap"] 
          as AssetPropertyString;

      if( bumpmapBitmapProperty.IsValidValue( bumpmapImageFilepath ) )
        bumpmapBitmapProperty.Value = bumpmapImageFilepath;
    }
    editScope.Commit( true );
  }

Standard Material Schemas

• Ceramic
• Concrete
• Generic
• Glazing
• Hardwood
• MasonryCMU
• Metal
• MetallicPaint
• Mirror
• PlasticVinyl
• SolidGlass
• Stone
• WallPaint
• Water

Advanced Material Schemas

• AdvancedLayered
• AdvancedMetal
• AdvancedOpaque
• AdvancedTransparent
• AdvancedWood

Common Schema

Schemas for Connected Assets

• BumpMap
• Checker
• Gradient
• Marble
• Noise
• Speckle
• Tile
• UnifiedBitmap
• Wave
• Wood

UnifiedBitmap

Property Names

  AssetPropertyDoubleArray4d genericDiffuseProperty 
    = editableAsset["generic_diffuse"] 
      as AssetPropertyDoubleArray4d;

Equivalent:

  AssetPropertyDoubleArray4d genericDiffuseProperty 
    = editableAsset[Generic.GenericDiffuse] 
      as AssetPropertyDoubleArray4d;

Special Cases

  AssetPropertyString path
    = asset[UnifiedBitmap.UnifiedbitmapBitmap] 
      as AssetPropertyString;

• Path is relative if inside default Material Library or in Options/Rendering/Additional Render Appearance Paths;
• Path is absolute otherwise.

  AssetPropertyDoubleArray4d color
    = asset[Generic.DiffuseColor] 
      as AssetPropertyDoubleArray4d;

• The Value of this AssetProperty is ignored if there is a connected Asset.

• AssetPropertyReference reference – Does not have a Value. Used only to have a connected Asset.

AppearanceAssetEditing

Edit appearance asset properties via a small control dialog – this sample demonstrates basic usage of the AppearanceAssetEditScope and AssetProperty classes to change the value of an asset property in a given material:

• Bring up a modeless dialog
• Select a Painted Face
• Get Appearance Asset
• Get Tint Color AssetProperty
• Increment red/green/blue