## Monday, April 18, 2011

### Working with Schedules - Relationship between areas

In this recent thread on www.revitforum.org a question was brought op on how to calculate the Ratio between two Area Types. I’ve dealt with this a lot in trying to create a Template for Building Code Calculations, and came up with a solution.

A copy of the sample file used in this post is found here.

The problem with Revit Schedules is that it’s not possible to make calculations based on a Grand Total. Revit will only calculate per row, and this might not be what you’re after.
An important rule in the Dutch Building Codes, the 55% rule: 55% of the usable area of ​​a building (“gebruiksoppervlak”) must be qualified as suitable for the long-term presence of people (“verblijfsgebied”). This kind of Area is required to meet all kinds of rules that we just ignore. This blog is about the question: how can I calculate the ratio between “gebruiksoppervlak” and “verblijfsgebied”?

Simple Floor Plan with Rooms assigned

To begin, I just modelled a very simple geometry and placed some Rooms. Now it is important to identify the Rooms that actually belong to the type “verblijfsgebied”. As mentioned, the the rules for assigning a Room to the type “verblijfsgebied” are left for another time, so I pick a random room that I want to assign as a “verblijfsgebied”, while the rest is going to be assigned to “gebruiksoppervlak”. The assignment of a room or area to a certain Building Code Type is still fairly easy:
1. Create a Shared Parameter "VO_naam" for the type of Room and / or Area. This is a text parameter. Group the Parameter under Identity Data, make it an Instance Parameter and assign to the appropriate Category, in this case Room (which can also be Areas).
2. Give the various Rooms correct values of the parameter, in this case and GO and VG1.
3. Make a Schedule of room. Add the following fields:
a. Name
b. Area
c. VO_naam

Room Schedule filled with 3 parameters

4. Add a Calculated Value "VO_oppervlak" as an Area Parameter but you leave the formula field temporarily blank, it will later be filled on a later occasion.

Now it gets more complicated: how can a Revit decide whether a room belongs to “verblijfsgebied” (VO) or “gebruiksoppervlak” (GO), and how to calculate the proper Area?

First off, let’s start with defining the type of Room. To define this a Yes/No Parameter can be used: the user manually checks off whether a Room belongs to the VO or the GO. There is also a more automated (but also complicated) way: by using a so-called Key Schedule. The Dutch Building Code has but a limited number of types of rooms. That certain types of rooms have properties and rules assigned to the, and one of them is whether the type of Room belongs to the VO or GO. Since the Key Schedule can also be used for other purposes and calculations, this method is applied here.

1. Create a Key to Schedule: View Tab> Schedule. Select as a type of Schedule the Room Schedule and select Key Schedule.
2. Assign a Key Name and an additional parameter: OF_VO (Conversion Factor_VerblijfsOppervlak). This is an Integer.
3. Press the right mouse button in the Schedule View and choose Add Row. Add as many rows as desired.
4. After adding the appropriate rows can be filled the different types. Additional Rows may be added at any time during this excersize. Fill OF_VO parameter. In this case, only the Room Type “verblijfsruimte” is part of the VO (value 1) and the rest of the room types are part of the “gebruiksoppervlak” (value 0).

Setup of the Key Schedule

Once this is completed you can return to the Room Schedule and add the Parameters from the Key Schedule to the Fields in the Room Schedule.
Next, select the parameter VO_oppervlak again and press Edit. In the Formula bar add the following formula: Area * OF_VO. Because you have indicated in the Schedule Key that only the Rooms with the Room type "verblijfsruimte" have a conversion factor of 1, the result of this formula will be 0, unless the Room Type ‘verblijfsruimte" is applied.

Room Schedule with automatic calculation of Area types per room

Second: how can we calculate the Ratio between two types of Area? This cannot be done without some trickery. The problem is, that I can format the Schedule in a way that it will only show two rows, one with VO_naam set to GO and one with VO_naam set to VG 1. I can also create a Ratio-parameter which calculates the Ratio between the two. Just add the Parameters Ratio = Area VG / Area GO.
But, there are a few rules to using Schedules for calculations which causes problems:

1. Revit will calculate a formula for each Room. This DOESN’T change when Itemize Every Instance is unchecked.
2. In other words: unchecking Itemize Every Instance does NOT change the outcome of any given Calculated Value in the Schedule. It will look this way because Revit can add up the outcome of all Rows that are hidden, but the outcome of each Room is still the same. In this case we want to reference to the Grand Total Area so this causes a erroneous outcome of the formula:
3. The formula will read Area VG / 0 = (cannot be solved), when the Room is assigned to Room Type “VG”.
4. The formula will read 0 / Area GO = 0, when the Room is not assigned to Room Type “VG”.

This outcome is shown in the next few figures and was also the problem in the message posted on Revitforum.

Even though the Grand Totals are correct, the calculated Ratio stays 0%

But how can we now calculate the ratio between “verblijfsruimte” en “gebruiksoppervlak”? For starters, go to the Formatting Tab an check the box Calculate Totals for Area and VO_oppervlak. Then go to the Sorting And Grouping Tab, set Sort By VO_naam on and check Grand Totals.

Switch to “Sorting and Grouping”, Sort By “VO_naam” and check Grand Totals.
After this we create an additional Calculated Value. Create a Calculated Value of the type Percentage and divide Area by .This shows the percentage of a single Room to the overall Grand Total Area.

Calculated Value Verdeling VO_GO

After this we create another Calculated Value, “Area_totaal” with the formula: “Area / Verdeling VO_GO”. With this parameter the Grand Total Area of all Rooms is calculated . Crucial in this step is that the Grand Total Area now is a Room Parameter and therefor appears on each Schedule Row. This makes it possible to use this value in further calculations.

The third Calculated Value is “Percentage_VO” and uses the formula “Verdeling VO_GO / Area_totaal”. This parameter calculates the total percentage of Room type “verblijfsruimte”.
Finally a Calculated Value “Percentage_GO” is created with the formula “(Area-Distribution VO_GO) / Area_totaal”. Theoretically, also the formula “100 - Percentage_VO” could be used, but this formula gives a good check if everything is calculated and whether all available Rooms have been assigned to a certain Room Type.

Calculated Value Area_totaal

Calculated Value Percentage_VO

Calculated Value Percentage_GO

It should now only be a matter of setting the proper Schedule Formatting. The columns

“Name”, “Area”, “Type ruimte”, “OF_VO”, “Verdeling VO_GO” en “Area_totaal“ can be hidden in the Schedule. Click the right mouse button on the column and select Hide Column. Then go to the Sorting And Grouping tab and uncheck "Itemize Every Instance”. Next, in the Format tab, the formatting of the columns “Percentage_VO” and “Percentage_GO” can be adjusted. Set the Units to Percent, 2 decimal places and with the unit symbol %. The end result should look something like shown in the figure below.

Final result

Does this work with multiple types of Rooms? To investigate this I added a new Phase and an extra room. This also gets as Type "verblijfsruimte" but named VG 2. Now the intention is that both the individual percentages and the total Ratio is calculated. The final result below shows that the desired outcome is indeed shown in the Schedule.

Filling Room Type and VO_naam provides with an accurate Schedule

### My first API part 4

Setting up the coding file Class1.cs

The actual coding of your Addin will be taking place in separate *.cs files. In the default template Class1.cs is already predefined. Class1.cs file can contain all code for a complete piece of software. This is probably best if you have a simple piece of software, but in more complex solutions this will become very confusing. In this case, you can create multiple *.cs files for different parts of the software.

So, start with renaming the default Class1.cs to a more suitable name, in this case I renamed it to TestClass.cs. I am told to always use the naming format DescriptionClass, so you can later see that it’s a Class file. Apparently there are also other types of cs-files, but I haven’t come across them just yet… (except off course the AssemblyInfo.cs, but this is in a different section of the Solution Explorer).

After this there are some other default settings that have to be applied.
The first four lines state which parts or containers of the .NET is going to be used. Default parts are the standard system containers. Since we are creating a Addin for Revit, we will also be using containers from the Revit API.

So, place the cursor after the fourth line, hit enter a few times to free up some space and start typing:
using Autodesk.Revit.UI (this allows you to access Revit commands such as move, etc)
using Autodesk.Revit.DB (this allows you to access the Revit Database)
using Autodesk.Revit.Creation (this allows you to automatically and place create Revit Components)

Creating the extra Revit based Executive Commands

As you type you will notice that VS presents possible textstrings. This is very helpful in selecting the proper code. When the previews are shown, you can use the arrowkeys to get to the right one and hit Enter. This will automatically fill in the text in the coding screen, thus preventing a lot of typing mistakes.

End the line with a semicolon. It’s always needed to end a line with a punctuation mark. This is usually the semicolon, except when there is a bracket of any kind.
Besides this: keep in mind that these textstrings are case sensitive.

Depending on the type of Addin you want to create there will probably a need to also add some of the system containers too:

Using System.IO; (which allows you to read and write files)
Using System.Windows.Forms; (which allows you to make screens, forms and with this create a user interface for your Addin).

When typing the Using System.Windows.Forms you probably noticed that there was NO automated fill-in of the commands by VS. This happened because the Reference with the .NET Class was not yet created for this command. To make this work, you will also need to go to the Reference subscreen, right click on Reference and select Add Reference.

Now go the .NET tab and select System.Windows.Forms to add it to the References.

Last remark before actually starting the programming

So, after this we’re kind of good to go. In the next parts of this weblog I’ll start trying to compile an Addin which allows you to automatically place Revit Components based on a point file.

Last tip I got before starting the actual work: when starting to program there’s a very useful viewsetting. Go to the View menu and click Error List. This opens up another subscreen which lists all coding errors (no errors does NOT mean the program will work, it just means there are no syntax errors in your code).

VS with Error List opened.

In this example the semicolon after the line “using System.Windows.Forms” is missing. You can double click on the error to jump to the text line to which it applies.

### Revit API, part 3

API Project Browser aka Solution Explorer

What does the Solution Explorer contain? First off, you can see it’s sort of the same treelike sorting that Revit uses. On top, you start with the file itself, being Solution ‘ClassLibrary1’. This contains three parts:

1. Properties
2. References
3. Files

Properties

The Properties part contains well, the project properties. Double click on the AssemblyInfo.cs file and this will pop up:

AssemblyInfo.cs

There are a few things you should know about the format off coding and then this whole thing will start to make sense.

First off, the dark blue text is an executive command. Do this, look there, etc. So this code starts with defining which parts of the .NET building blocks are used. Like Revit uses classes (Door, Window, Wall, etc) the API also uses classes. Like the Revit classes these API classes have different behavior and usability. So, when you start to write a piece of code, you´ll need to specify in which classes you want to be digging around. No worries though, this can be edited throughout the whole process of writing the software.

The light blue text is a sort of parameter. What needs to be handled? In this case the executive command is to build an assembly with a number of parameters like Title, Description, etc.

The “red text” is just that: a text. In these case the parameters are text parameters. The infilling data has to be placed in between double quotation stabbings (and turns red if you do so)

Next the //green text//: this is actually a way to place notes within the code without it being used in the software that you are writing. So you use this to add notes, descriptions, clarifications and sometimes random mumbling when it all becomes too much to handle.

Then comes a few lines of codes which fill in the actual information about the Assembly (piece of software) you are making. It’s formatted like this:
[Executive command: Parameter("Text description")]

Notice that an executive command is always in between [], and a parameter is also in between ().

First line of this part defines that the piece of software will be named ClassLibrary1
Second line leaves a blank description for it, etc.
You can fill this out at your own wishes.

I´ve filled out all text parameters and added some remarks. Then Save All

Working in VS means you are working with different files. All *.cs files are parts of the project. So if you want to save your project, you don’t use Save but use Save All (on the right side of the Save button). When saving all for the first time you will get a popup asking where the project should be saved. If you leave the checkbox “Create directory for solution” checked it will automatically create a Windows folder in which all parts are saved. After saving you will notice that the naming of the file on the right has changed.

Also note that every change you make in the coding screen will leave a yellow marking in front of the text line. After saving, these markings will turn green.

References

The References define the .NET containers that you want to use. In this case, some System containers. Don’t quite know what they do, but since they were in the Template I’ll leave them be.

BUT, since we’re trying to create a Revit plugin, you will need to reference to the Revit program too. To do this, you’ll need to load two Revit DLL’s: RevitAPI.dll and RevitAPIUI.dll. This will actually tell the Addin that it’s supposed to work with Revit.

To do this, right-click on References and select Add Reference. In the Popup screen go to Browse and find these two files in the Revit program folder: RevitAPI.dll and RevitAPIUI.dll.

## Thursday, April 7, 2011

### Autodesk WikiHelp

Autodesk has recently unveiled a new website called Autodesk WikiHelp. As with any wiki site it in almost purely user supported with content, although Autodesk has started it out already with many sections full of content. This seems like a really great idea and the process to submit information is relatively painless. When you find a page you would like to add information to click "Edit Page" then type what you would like to, save, agree to their terms, and then wait for it to be approved (approximately one day the times I have submitted).

There are a few drawbacks I found, one is the log in...I am not sure if perhaps I did it wrong, but it seems to me that I now have an Autodesk login, Autodesk Student Community login, Autodesk AU login, and others....sure would be nice to just have one login and one profile. The other drawback I see is actually getting people to submit on it, right now there are many forums and blogs out there on Autodesk, Revit, BIM, etc...this is just one more site in the array of resources.

All in all this is a really cool website, one of my favorites is their video of Revit 4 which takes me back to when I first started Revit and makes me appreciate the new UI and all the other great additions they have done to Revit since....

## Tuesday, April 5, 2011

### My first API, Part Two

In this part we’re going on a first exploration of Visual Studio 2008. Mind you: this is not a VS course. I will only highlight the parts I have used so far, probably disregarding a lot of extremely valuable functionality. And perhaps in a complete non-logical way. But hey, this is about Revit. Not VS. Go buy a book…

Visual Studio 2008
So, halfway through the day, I get to actually start up VS and go to work. Since Microsoft started deploying VS 2010, the 2008 version can no longer be downloaded from their site (or at least, I couldn’t find it). Luckily for me, and anyone else reading this and wanting to start: I posted the installer on www.revitforum.org and will also be posting it on my own blog at www.mdr-advies.nl.
After installing it, you get the screen as shown in the picture below.

Visual basic startup screen

You can start by opening a new project through the Recent Projects subscreen, in which case the following screen will open.

Start a new project

There are some different templates, which I haven’t all figured out quite yet. If memory serves me well, these are the different types:
• Windows Form Application: This is a standalone windows application with no interaction to other running programs.
• Class Library: This is the one you will mostly need, a plugin inside a host software.
• WPF Application: I have no clue as to what this does… Any comments from the API gurus out there?
• WPF Browser Application: Same here…
• Console Application: these are pieces of software that run automated without any user input. These are those MS-DOS-boxes that float around from time to time when installing software. Usually they perform tasks like extracting files to a certain folder, or cleanup installation files after Setup.
After starting a Class Library Template you will see this screen:

Class Library Template startup screen

First off: what in the world does this all mean?
The big screen is the coding screen, here you create the actual program code that makes your Addin do stuff. On the right side there is a palette which contains all sorts of project data. In Revit terms, this would be the project browser. Let’s focus on that one in the next post...

## Monday, April 4, 2011

### My first Revit API, Part One

My first Revit API, pt 1

For starters

So, I finally came to it. After nearly a year of lurking around in the deep dark depths of Revit’s Advanced Programming Interface (API) I took the plunge and had my first crash course in API.

First of all: I never ever did any programming before I started this. Not in Visual Basic, C# or even a Lisp routine for Autocad. My strengths, if any, lie within the normal use of Revit, with the UI (User Interface). I work my miracles at the front end, sort of speak. But, that side has it’s limitations, and that’s why I ultimately decided to cross over to the dark side…

Due to my complete lack of programming knowledge, I’m taking babysteps. I did find however that I have one big advantage over the “traditional” programmer: I know my way around in Revit. I know it’s functions, it’s language

and it’s quircks. That gives this puny mortal hope. This blog is about my experiences while trying to understand how Revit works under the hood.

HOWEVER: This blog is meant to give others like me some grip on working with the API. But it’s far from complete, and cannot be trusted to be accurate nor complete, since I know as little about this as you do… Do I need to further emphasize the fact that I cannot be held accountable for any damage, direct or indirectly resulting from reading this blog and/or referencing to it’s contents?

Now, since the “official” part is over, what do you need to start with API programming? First off:

• A major dose of pain killers to rub off the headache of your first day off staring at a complete textstring madness. I for one settled on a few big scotches afterwards, but to each their own. Seriously though: this is heavy stuff. Do not try to squeeze it in between normal daily routine. Free up time!
• You can start with buying half a dozen biblesized books about programming in C# or VB.NET, which will without a doubt give you serious suicide cravings. It’s like learning Revit in Chinese mode without a dictionary. But the Revit community also provides with a lot off resources. Pay special attention to Jeffrey Tamnik’s weblog, The Building Coder. If this guy can’t do it, it cannot be done. Or post at Revitforum.org, since we have some great API guys too. Truth of the matter is, when you’re familiar with Revit, the code will make sense if you trust your instincts.
• Install Visual Studio Express Edition. It’s free, easy to use (really) and has more capabilities then the native Revit program interface. Check out which version goes with the Revit version you want to program for. For instance, Revit 2011 works with Visual Studio 2008. Not all versions work the same so you need to be clear on this one.

Some context

My first day started with a brief history of programming, which I will spare you from. Let’s just say that, in this day and age, most of the programming languages are quite similar. Differences between C# (by the way, this is pronounced C Sharp) and VB (Visual Basic) are comparable to dialects: most of the time It’s quite the same, and every once in a while you will completely misunderstand the other language.

With all different languages that are floating around, thousands of parties writing software and re-inventing the wheel, there has to be some generalization. A Style Guide sort of speak. This is where .NET (pronounced Dot Net) comes in. Microsoft .NET is kind of like a huge pile of LEGO elements which you can pick from to put together your program. It offers standards for commands, actions, descriptions and everything else you need to build your software. Why does all Windows Software look and feel the same? Because it’s all compiled in .NET.

We could go into a heated argument that this creates a mass culture where nothing stands out. I, for one, am thrilled if the freaking thing works and don’t really care what it looks like. If I can use .NET to type in a simple textstring command in Visual Studio and it automatically creates a Pick File screen like the one below, who cares what it looks like?

 Standard .NET functionality: Forms and screens.

So it comes down to this:

C# / VB = programming language

.NET = a standard interface which contains basic templates, commands, etc which allow a programmer to work faster, more accurate and gives an universal look and feel to the programmed software.

API = the part of a software product (in this case Revit) which contains all rules and commands specific to this software. It’s the portal between Revit and the outside world. Everything that comes into or gets out of Revit goes through the API.

Visual Studio = a piece of software that lets you write another piece of software. VS “knows” all three of the above, and ties them together. Using VS you can tie Commands from the Revit API (Place Component) into a Windows Form (such as the Open Form) using the C#.NET programming language.

Try wrapping your head around that one for a while before we continue. Took me a whole lunchhour…

Next Part: Visual Studio 2008...