Image courtesy of Hobart, Yañez, Ramos, Maguey, and Martínez
CP231-2: Putting the “I” in BIM
Revit API Parameters In-Depth
Matt Mason
Director, Software Development, IMAGINiT Technologies
Agenda

Introductions & Goals

Parameter Fundamentals
Parameter API Fundamentals
The Parameter API in depth:






Reading, Setting, Creating, Hiding
Parameters and Families
Things to Do With Parameters
Importing and Exporting Data

Reporting
 Validation and Cleaning Up
Introduction
Matt Mason
Director, Software Development,
IMAGINiT Technologies (merged with Avatech Solutions)


Veteran of 80 Small/Medium Revit API projects and 9 large API
projects over 6 years.
Packaged Software Developer:
•
Avatech Utilities for Revit
• BIMreview – now Autodesk Revit Model Review
• Scan to BIM for Revit
Occasional Revit API Blogger at: http://cadappdev.blogspot.com
Audience Survey
What Type of Company Do You Work For?
Architecture Firm
A/E/C Firm
Software Firm
Educational Institution
Other?
Audience Survey
Which flavor(s) of Revit are you interested in?
Architecture
Structure
MEP
Audience Survey
Amount of Revit Experience?
None?
A little?
A lot?
Expert?
Audience Survey
Amount of Revit API Experience?
None?
A little?
A lot?
Expert?
The “Revit API Track”
Id
Title
Speaker
CP220-2
Introduction to the Revit API
Rod Howarth
CP228-2
Optimal Use of New Revit 2011 Programming Features Jeremy Tammik
CP231-2
Putting the “I” in “BIM”: Parameters in the Revit API
Matt Mason
CP234-2
Exactly What You Want, and Faster: 2011
Programming Optimization
Jeremy Tammik
CP316-1
Presenting Your Analysis Data in Revit 2011
Harry Mattison
CP319-1
Analyze the Geometry of Buildings using the Revit API
Scott Conover
CP327-1
Applied Dynamics: Using Dynamic Model Update in the Scott Conover
Revit API
CP316-3U
All Systems Go: The Revit MEP API
And More!!!
Jeremy Tammik
Goals and Housekeeping

60-minute class

In depth coverage of Parameters and the Parameter API
 Examples to inspire what’s possible
Housekeeping
 All samples are in C#
 Samples are posted online
 Use http://converter.telerik.com to convert to VB.NET if desired
Why Parameters?



Parameters were the first API
Parameters are STILL the most powerful API
Parameters are a big part of the “I” in “BIM”
Quick Parameter Fundamentals



Where do parameters come from?
Where do they live?
Which parameters will be on a certain kind of element?
Quick Parameter Fundamentals: Shared
Shared Parameter: Guaranteed to be recognizable and unique
across all Revit families and projects.
# This is a Revit shared parameter file.
# Do not edit manually.
*META VERSION
MINVERSION
META 2
1
*GROUP
ID
NAME
GROUP 1
test
*PARAMGUID NAME DATATYPE
DATACATEGORY
PARAM ebe91ef6-0ec6-4e1a-aec0-5344a0556bbc SurfaceArea
GROUP VISIBLE
AREA
1
1
Parameter API Fundamentals
Element
- Id
- Category
- BoundingBox
- Parameters
...
Parameter
- Definition
- DisplayUnitType
- Element
- Id
- IsReadOnly
- IsShared
- GUID
- StorageType
Definition
- Name
- ParameterGroup
- ParameterType
Internal
-BuiltInParameter
External
-GUID
-Visible
Parameter API Fundamentals
From Elements to Parameters:
// get our active document
Document doc = commandData.Application.ActiveUIDocument.Document;
// get the element we care about. In this case, the project info:
Element projInfo = doc.ProjectInformation;
// go through all of the parameters and show them individually:
foreach (Parameter p in projInfo.Parameters)
{
TaskDialog.Show("Parameters", p.Definition.Name + ": " + p.AsString());
}
Parameter API In Depth: Values
Parameter Storage Types:
 String (Text)
 Double (Number)
 Integer (Whole Number)
 ElementId (Revit Element)
 None/Invalid
Reading Methods:
 AsString()
 AsDouble()
 AsInteger()
 AsElementId()
 AsValueString()
NOTE:
 Units are Revit internal
 Blank ElementId = -1
15
Parameter API in Depth
private string getParameterText(Parameter p)
{
switch (p.StorageType)
{
case StorageType.String:
return p.AsString();
case StorageType.ElementId:
ElementId eid = p.AsElementId();
if (eid.IntegerValue < 0) return "(none)"; // blank
// get the element, return the name
Element eObj = p.Element.Document.get_Element(eid);
return eObj.Name;
case StorageType.Integer:
return p.AsInteger().ToString();
case StorageType.Double:
// check to see if there's a value string first!
if (p.AsValueString() != null)
return p.AsValueString();
default:
return "N/A";
}
}
return p.AsDouble().ToString();
Quick Note: Schedule Keys are Elements!
16
Parameter API in Depth: Shorthand
// get right to reading the value:
String number = myRoom.Parameters[“Number”].AsString();
Parameter API in Depth: Type vs. Instance
Wall
WallType
(Instance
Parameters)
(Type
Parameters)
ElementId wallTypeId = myWall.GetTypeId();
Element myWallType = doc.get_Element( wallTypeId );
Double width = myWallType.Parameters[“Width”].AsDouble();
Parameter API in Depth
BuiltIn Parameters
 Currently about 3000 of them
 All contained in the BuiltInParameter enum
 May or may not be “visible”
// get our active document
Document doc = commandData.Application.ActiveUIDocument.Document;
// get the element we care about. In this case, the project info:
Element projInfo = doc.ProjectInformation;
// get the builtin parameter
Parameter p = projInfo.get_Parameter(BuiltInParameter.PROJECT_NAME);
TaskDialog.Show("Project", "The project name: " + p.AsString());

Other advantage: no language issue
Parameter API in Depth: RevitLookup


Key part of the development process
Now part of the SDK
Parameter API in Depth: Setting

Based on the parameter storage type:

Set (String): Text
 Set (Double): Number – usually in Revit’s internal units
 Set (Integer)
 Set (ElementId): The ElementId (or -1 for blank)

SetValueString( string ): A dimension value in user units (i.e. 5’ 7”)
Parameter API in Depth: Setting
Parameter param = myWall.get_Parameter(
BuiltInParameter.WALL_USER_HEIGHT_PARAM);
// setting the parameter by internal value (decimal feet)
param.Set( 20.5 );
// setting the parameter by the Display Value
param.SetValueString( "20' 6\"" );
Parameter API in Depth: What Can We Change?

Nothing is documented
Everything is experimental/investigative
The “IsReadOnly” is the key

Typical Wall:


Read-Only Parameters
Writable Parameters
Area, Base Extension Distance*, Base is
Attached *, Length, Related To Mass, Top
Extension Distance *, Top is Attached *,
Unconnected Height *, Volume
Base Constraint, Base Offset, Comments,
Location Line, Mark, Phase Created,
Phase Demolished, Room Bounding,
Structural Usage, Top Constraint, Top
Offset,
* These may be writable depending on other parameters/situations
Parameter API in Depth: Creating Parameters


Create Shared Parameters
Created via the DefinitionFile class
Parameter API in Depth: Creating Parameters
// get the shared parameter file
DefinitionFile file = app.OpenSharedParameterFile();
// if our group is not there, create it
DefinitionGroup group = file.Groups.get_Item("Room");
if (group == null) group = file.Groups.Create("Room");
// add our parameter to the group
Definition def =
group.Definitions.Create("Target Area", ParameterType.Area, true);
// now if we want it in the project, we need to bind it to categories
CategorySet cats = app.Create.NewCategorySet();
cats.Insert( doc.Settings.Categories.get_Item(BuiltInCategory.OST_Rooms));
// create a binding - instance or type:
InstanceBinding bind = app.Create.NewInstanceBinding(cats);
doc.ParameterBindings.Insert(def, bind, BuiltInParameterGroup.PG_AREA);
Parameter API in Depth: Hiding Parameters

Shared Parameters can be marked as HIDDEN

Visible to the API but not to the end-user

The parameter stays hidden forever!
Parameter API in Depth: Hiding
// get the shared parameter file
DefinitionFile file = app.OpenSharedParameterFile();
// if our group is not there, create it
DefinitionGroup group = file.Groups.get_Item("ID");
if (group == null) group = file.Groups.Create("ID");
// add our parameter to the group
Definition def =
group.Definitions.Create("Copyright", ParameterType.Text, false);
CategorySet cats = app.Create.NewCategorySet();
cats.Insert(doc.Settings.Categories.get_Item(BuiltInCategory.OST_SpecialtyEquipment));
InstanceBinding bind = app.Create.NewInstanceBinding(cats);
doc.ParameterBindings.Insert(def, bind);
Parameters and Families


Family API works differently with parameters
Everything done via the FamilyManager class
if (doc.IsFamilyDocument)
{
FamilyManager manager = doc.FamilyManager;
TaskDialog.Show("Family",
"There are " + manager.Types.Size.ToString() + " sizes");
}
Parameters and Families
Use the FamilyManager to:
 Add Parameter (add a family parameter or a shared parameter)
 Swap Instance/Type parameter definition
 Set
 SetValueString
 SetFormula
 MakeReporting / MakeNonReporting
Parameters and Families
private void setFamilyParams(Document doc)
{
FamilyManager manager = doc.FamilyManager;
// lookup the family parameters
FamilyParameter manufacturer =
lookupFamParam(manager, "Manufacturer");
FamilyParameter partNumber = lookupFamParam(manager, "Model");
// set them
manager.Set(partNumber, "BR18054-1");
manager.SetFormula(manufacturer, "\"VIKING\"");
}
Parameters and Families
private FamilyParameter lookupFamParam(FamilyManager fm, string name)
{
// lookup the family parameter
foreach (FamilyParameter fp in fm.Parameters)
{
if (fp.Definition.Name.ToUpper() == name.ToUpper()) return fp;
}
throw new ApplicationException("Unable to find parameter: " + name);
}
Things to do with Parameters

Update Parameters

Family Parameter Update

Import/Export Data

Door Mark Update
 MEP Parameter Tool
 Translation (Revit Translation)
Validation
 Fire Ratings
 Model Review

Room Manager
 Export Keynotes
 Revit DB Link
Questions?
Next Steps…

Miroslav Schonauer’s “Storing Complex Per-Document and
Per-Instance Data in Revit”
Matt Mason
mmason@rand.com
Autodesk [and other] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to
their respective holders. Autodesk reserves the right to alter product and services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may
appear in this document. © 2010 Autodesk, Inc. All rights reserved.