CP231-2: Putting the “I” in BIMRevit API Parameters In-Depth

Matt MasonDirector, Software Development, IMAGINiT Technologies

Image courtesy of Hobart, Yanez, Ramos, Maguey, and Martinez

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 MasonDirector, 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 FirmA/E/C Firm

Software FirmEducational Institution

Other?

Audience Survey

Which flavor(s) of Revit are you interested in?

ArchitectureStructure

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 Revit API

Scott Conover

CP316-3U All Systems Go: The Revit MEP API Jeremy Tammik

And More!!!

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 MINVERSIONMETA 2 1*GROUP ID NAMEGROUP 1 test*PARAMGUID NAME DATATYPE DATACATEGORY GROUP VISIBLEPARAM ebe91ef6-0ec6-4e1a-aec0-5344a0556bbc SurfaceArea 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());

}

15

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

16

Parameter API in Depth

private string getParameterText(Parameter p)

{

switch (p.StorageType)

{

case StorageType.String:

return p.AsString();

 

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();

return p.AsDouble().ToString();

 

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;

 

default:

return "N/A";

}

}

Quick Note: Schedule Keys are Elements!

Parameter API in Depth: Shorthand

// get right to reading the value:

String number = myRoom.Parameters[“Number”].AsString();

Parameter API in Depth: Type vs. Instance

ElementId wallTypeId = myWall.GetTypeId();Element myWallType = doc.get_Element( wallTypeId );Double width = myWallType.Parameters[“Width”].AsDouble();

Wall

(InstanceParameters

)

WallType

(TypeParameters

)

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:

* These may be writable depending on other parameters/situations

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,

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 Door Mark Update MEP Parameter Tool Translation (Revit Translation)

Validation Fire Ratings Model Review

Family Parameter Update

Import/Export Data Room Manager Export Keynotes Revit DB Link

Questions?

Next Steps…

Miroslav Schonauer’s “Storing Complex Per-Document and Per-Instance Data in Revit”

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.

Matt Masonmmason@rand.com