Several queries concerning rendering issues were discussed recently and solved by the new Visual Materials API included in Revit 2018.1:
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:
For the sake of completeness and search engine findability, here is the pure text copied out of the slide deck:
- Learning Objectives
- The Basics
- New Editing Capabilities in Materials API
- Schemas and Property Names
- SDK Sample
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
