The Building Coder

CouchDB Implementation and GitHub Repository

I more or less completed the research for my cloud-based round-trip 2D Revit model editing project.

I'll describe some parts of that, and also address

• Three aspects of life and programming
• Room editor navigation
• Nested asynchronous database call-back functions
• Roomedit – my first GitHub project
• Debugging JavaScript with Firebug
• Screen snapshots on mobile devices
• Open source components used by Autodesk
• Retrieve slabs above specific walls

Lazy, Simple and Perfect

You will like the first slide of my upcoming tech summit presentation.

I start off with a couple of quotes on three fundamental aspects of software engineering and life in general:

• Lazy
• ... develop the three great virtues of a programmer: laziness, impatience, and hubris – Larry Wall
• Simple
• Simplicity is the ultimate sophistication – Leonardo da Vinci
• There is no greatness where there is no simplicity – Leo Tolstoy
• KISS
• Perfect
• Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away – Antoine de Saint-Exupéry

Basically, I demonstrate how easy it is to implement simple model navigation and 2D graphical editing using server-side scripting so that it works on all mobile devices.

So it is all about keeping it simple and easy.

Room Editor Navigation

The last instalment on this topic included a two-minute minimal demo recording illustrating its use and started describing the simplest aspect of the implementation, the server-side generated index.html home page that lists all models and prompts to select one of them.

From there, one navigates through the hierarchy of model > level > room > furniture and equipment. The latter finally reference the symbol objects that determine their geometry.

Now lets move on to the more interesting parts where the inter-related objects need to execute more complex queries to establish their relationships. I still have not covered the juicy part of rendering the SVG model, and the even juicier part of interacting with it, editing it, and updating the database with the changes made, either.

As said, the navigation logic is pretty trivial:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

Basically, the entire implementation is all squeezed into one single overgrown index.html file.

Moving on from the home page to the second simplest part of it, we have selected a specific model and list all the levels it contains.

This navigation takes place by invoking the same index.html URL and adding a modelId parameter to it.

This parameter is picked up and used to query the database for all levels in the specified model.

To retrieve only the required ones, I use a CouchDB view mapping model id keys to level documents like this:

  map_model_to_level = {
    map: function (doc) {
      if( 'level' == doc.type ) {
        emit(doc.modelId, doc);
      }
    }
  };

I can specify a key to CouchDB when querying this view, i.e. make a REST API call with a parameter like this:

  .../roomedit/_design/roomedit/_views?key=12345

This will retrieve only those level documents from the database whose modelId value matches the given key.

Here is the part of index.html handling that interaction:

. . .

else if ( paramdict.hasOwnProperty( 'modelid' ) ) {

  //======================================================
  // display a menu of all levels in selected model
  //======================================================

  var mid = paramdict['modelid'];
  db.getDoc( mid,
    function(err,resp) {
      if (err) {
        return alert(JSON.stringify(err));
      }
      var modeldoc = resp;
      db.getView('roomedit',
        'map_model_to_level',
        { key: JSON.stringify(mid) },

        function (err, data) {
          if (err) {
            return alert(err);
          }
          var n = data.rows.length;
          for (var i = 0; i < n; ++i) {
            var doc = data.rows[i].value;
            if( doc.modelId != mid ) {
              alert( 'model ids differ: doc '
                + doc.modelId + ", url " + mid );
            }
            var s = url + '?levelid=' + doc._id;
            $('<li/>')
              .append($('<a>').attr('href',s).text(doc.name))
              .appendTo('#navigatorlist');
          }
          var p = $('<p/>').appendTo('#content');
          p.append( $('<a/>').text('Home').attr('href',url) );
          p.append( document.createTextNode( three_spaces ) );
          p.append( $('<a/>').text('Back').attr('href',url) );

          $('<p/>')
            .text( 'Please select a level in the list below.' )
            .appendTo('#content');

          var table = $('<table/>').appendTo('#content');
          table.append( '<tr><td>' + 'Model:'
            + '</td><td>' + modeldoc.name + '</td></tr>' );

          var prompt = n.toString() + ' level'
            + pluralSuffix( n ) + ' in model ';

          var p = $('<p/>').text( prompt ).appendTo('#content');
          p.append( $('<i/>').text( modeldoc.name ) );
          p.append( document.createTextNode( dotOrColon( n ) ) );
        }
      );
    }
  );
}

As I already mentioned, this is populating an super simple HTML skeleton containing the following nodes:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

Here is the result in a model named 'Roombook' containing a single level 'Fondations':

Nested Asynchronous Database Call-back Functions

One challenge for me in the room editor CouchDB implementation was understanding how the asynchronous database call-back functions work, and how I can nest them to retrieve all the results I need.

In the case above, the situation is still very simple: I need to perform two database queries:

• Query a specific document, the model, using the db.getDoc function.
• Query all the levels it contains, which are returned by the map_model_to_level view with the model id key, using the getView function.

Both the getDoc and getView functions take an asynchronous call-back function as an argument.

I found out the hard way that I can nest these within each other to ensure that I have all up-to-date results before I display my page.

This gets a bit more hairy as the number of queries and thus the number of nested functions grows...

Roomedit – My First GitHub Project

Anyway, I have it all happily running now, and published the roomedit CouchDB application implementing this as my first ever GitHub project.

Debugging JavaScript with FireFox FireBug

Everybody makes errors. In my HTML and JavaScript code, these sometimes caused my index.html not to display anything at all.

Often this was due to some trivial JavaScript typo that would have been really hard to chase down.

Enter Firebug, thank God.

This is a great tool that I have started to rely on greatly to help me out of tight corners.

The Firebug debugging console is integrated in FireFox and includes support for examining and debugging all kinds of aspects of a web page.

You can open the Firebug console on any web page through Tools > Web Developer > Firebug > Open Firebug. That displays a new panel at the bottom of the browser with tabs for

• Console
• HTML
• CSS
• Script
• DOM
• Net
• Cookies

I use Console and Script, mostly.

The former displays the location of a JavaScript error and jumps to it when loading the file. It also lists the URLs visited and stuff like that, which is very useful for analysing the REST API calls being made.

The script tab provides a JavaScript debugger allowing you to set breakpoints and analyse variable values etc.

There are lots of tutorials and documentation available on this feature, such as these ones on Firebug and JavaScript debugging, so I will not trouble you any further with my description.

To tell the truth, though, I never looked at any of them.

The thing just worked for me, is incredibly valuable, and I am grateful.

Screen Snapshots on Mobile Devices

Here is a quick guide how to create a screen snapshot on various types of mobile devices:

• iPhone – Press the Sleep/Wake and Home buttons together; the screen will fade temporarily, signalling that the screen shot was saved in your Camera Roll:
  
• Android – Press the Power and Home buttons together, or hold down the Lock/Power and Volume Down buttons together:
  
• Windows 8 – Press the Lock/Power and Home/Windows buttons together:
  

Open Source Components used by Autodesk

A colleague pointed out this open source repository containing all open source components used in AutoCAD, Map 3D and other Autodesk products.

I was actually surprised how short the list is. Anyway, it might be useful to know about.

Retrieve Slabs Above Certain Walls

Let's wrap this up with a standard Revit API question:

Question: I want to determine the slab above the walls of a particular room.

How can retrieve those using the Revit API, please?

Answer: As so often in Revit, there are a number of different possibilities, and it depends in part upon how the building has been modelled.

In a structural model, you may be able to query the analytical support data. I have no idea whether this information is included there, but my naive assumption would be that this should be possible.

Much more generally, you can analyse and query the geometry in a number of different ways.

The two possibilities that immediately spring to mind are:

• Use the ray casting functionality provided by the Document FindReferencesWithContextByDirection method and the ReferenceIntersector wrapper class.
• Use the geometric proximity functionality provided by some element filters, e.g.

The discussion on determining the columns supporting a beam demonstrates several different variations of the latter. Earlier blog posts include examples of the former as well.

Response: I was able to use the functionality for finding the supporting columns for beams from your link to solve my issue as well.

In my case, beam.GetGeneratingElementIds returns the desired supported floors.

I also tested using an ElementIntersectsSolidFilter to retrieve all walls that intersect the floor using the floor solid geometry object:

  Solid solid = null;
  ElementFilter slabIntersectFilter
    = new ElementIntersectsSolidFilter( solid );
 
  FilteredElementCollector walls
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .OfClass( typeof( Wall ) )
      .WherePasses( slabIntersectFilter );

This also solved my issue. It can be the alternative when beams are not there.

My Cloud-Based 2D Editor Implementation and Status

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, here are some issues I tackled since my last report:

• Updated project description and status
• CouchDB SVG editor implementation
• Home page: list all models and select one

Updated Project Description

I originally thought I would be implementing three cooperating components: the Revit add-in, a cloud-based data repository, and a browser-based JavaScript SVG viewer and editor client for the mobile devices.

After struggles with and resolution of the same origin policy, I discover that I need to use server-side scripting instead, which moves all the JavaScript and SVG handling to the cloud-based data repository component as well.

I updated my proposal accordingly as follows:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device
using Server-side Scripting, CouchDB and SVG

I demonstrate round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser.

How can this be achieved?

A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository implemented using a CouchDB NoSQL database.

On the mobile device, the repository is queried and the data is rendered in a standard browser using server-side generated JavaScript and SVG.

The rendering supports graphical editing, specifically translation and rotation of the furniture and equipment.

Modified transformations are saved back to the cloud database.

The Revit add-in picks up these changes and updates the Revit model in real-time.

All of the components used except Revit are completely open source.

This round-trip editing workflow is based on the following main components:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• A server hosted JavaScript SVG editor running in the browser on any device, rendering the model and supporting simple geometric modification of the model.

The presentation outline, the final proof of the pudding, looks like this:

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as a 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Watch the BIM in Revit auto-update.

I have now completed the implementation of all these steps with the single minute exception of the prefix 'auto'.

In other words, I currently have two commands in my Revit add-in:

• CmdUpload uploads the room and equipment boundary data to the cloud repository, either from a manually selected set of rooms, or all rooms in the model.
• CmdUpdate retrieves the changes applied to furniture and equipment on the mobile device. This is currently a command triggered by the user.

The next step for me will be adding the 'auto' to the update, i.e. the implementation of an external event that subscribes to changes in the cloud database caused by the user editing the furniture and equipment transforms on the mobile device and automatically applies real-time updates to the BIM.

Before I get to that, though, I have a huge backlog of information to share about all that has already been achieved, and how.

Without further ado, here is a little two-minute film demonstrating the current functionality to give you the idea:

CouchDB SVG Editor Implementation

I described the room editor database structure consisting of the model, level and room hierarchy.

Furniture and equipment instances are placed within the room and refer to separate symbol objects that store their geometry.

Two of the main tasks listed in my last to-do list were:

• Implement the rendering and editing of the 2D plan view in SVG on the mobile device.
• Reflect the modifications made back to the cloud-based CouchDB data repository.

Let's look at how I achieved that.

First, I must admit that I struggled quite a bit and burnt a significant amount of night oil on this. Maybe it would have been more efficient to do some reading up on basics before starting. Instead, I found various tutorials that did "almost" what I wanted that I tried to reproduce and tweak. Each and every one finally turned into a dead end, and I was thrown back to square one, or sometimes square 1.15 or so.

One impressive little sample application that really did help was Opto3, a small CouchDB application entirely hosted within CouchDB. It uses JQuery Mobile to serve a single-page mobile application that presents a four-panel drill-down approach to find an optometrist in a desired US location.

All the information stems from one single CSV file of US optometrician addresses. Here is its description, GitHub project repository and CodeProject article that also provides a useful list of additional references.

As said, I can use Kanso to maintain and install the database, push the views and upload my documents in JSON format to the local CouchDB database 'roomedit' using commands such as these:

$ kanso install

$ kanso push http://localhost:5984/roomedit

$ kanso upload mydata.json http://localhost:5984/roomedit

I ended up implementing my totally own version of a CouchDB application, unlike anything I saw in any of the samples.

Basically, I only use a couple of CouchDB views and a rather heavy-weight index.html file that renders them for various contexts, guiding the user through the model and room selection process and finally displaying the SVG editor page.

The selection logic is simple:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

The first three steps were not so hard once I understood about CouchDB views and discovered how to render them in index.htm.

Integrating the SVG editor posed some really tough problems, but ended up being really simple as well.

For a while I was unsure whether I would be able to use the Raphaël JavaScript SVG library as is, or whether it needed to be packaged as a Kanso package. As it turned out, that was not necessary. Until I discovered that the hard way, though, I tried to avoid the use of any non-Kanso libraries at all, and struggled with SVG editing issues instead.

So let's start by looking at the simplest step first, how to list all models and prompt the user to select one of them.

Home Page: List all Models and Select One

The initial home page of my application is very simple. It looks like this, listing the available models and prompting the user to select one of them:

I represent each Revit model as a separate CouchDB document. All the data it carries is inherited from the DbObj base class, which specifies its type "model", description and name. I populate the two latter with information from the Revit ProjectInfo singleton object, and I use the Revit UniqueId as the CouchDB document identifier as well.

The resulting CouchDB JSON representation of my sample model looks like this (copy to an editor or view the HTML source to see the truncated lines in full):

{
  "_id": "bf0552b6-b7f7-4331-96d5-b19843262895-00015084",
  "_rev": "14-4e1c947c3d3e354117a1f016f2e23f63",
  "type": "model",
  "description": "ProjectInfo Project Information <86148 Project Information>",
  "name": "room_with_hole.rvt"
}

CouchDB implements and extremely scalable architecture and can host millions of documents.

Views are used to efficiently extract the ones required. A view can implement a map and a reduce function. The map function identifies the documents of interest and maps them to a key-value pair. The optional reduce function can be applied to reduce the results by accumulation or other means. I have no use for reduce in my application.

To list all available models, I use an utterly trivial view function that does not even create real key-value pairs. All I need is to extract all model documents and list the model document information itself, so I just emit all model documents as keys directly:

exports.models = {
  map: function (doc) {
    if( 'model' == doc.type ) {
      emit(doc, null);
    }
  }
};

To render the results of the view into my HTML target file, I define the following scaffolding:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

In the JavaScript section, I require the Kanso db and jquery packages:

  var db = require('db').current();
  var $ = require('jquery');

The db package provides access to the current CouchDB database, and jquery is a Kanso wrapper for the standard jquery library.

Oh, and what is Kanso itself? Kanso is a framework enabling me to maintain my CouchDB views and other bits and pieces in standard file system files on the hard disk and upload them easily to the CouchDB database.

With that in place, the following JavaScript code queries the 'models' view and populates the HTML placeholder tags:

// display a menu of all available models

db.getView('room_loops', 'models',
  function (err, data) {
    if (err) {
      return alert(err);
    }
    var n = data.rows.length;
    for (var i = 0; i < n; ++i) {
      var doc = data.rows[i].key;
      var s = url + '?modelid=' + doc._id;
      $('<li/>').append($('<a>')
        .attr('href',s)
        .text(doc.name))
      .appendTo('#navigatorlist');
    }
    var p = $('<p/>').appendTo('#content');
    p.append( $('<a/>').text('Home').attr('href',url) );
    p.append( document.createTextNode( three_spaces ) );
    p.append( $('<a/>').text('Back').attr('href',url) );

    $('<p/>')
      .text( 'Please select a model in the list below.' )
      .appendTo('#content');

    var prompt = n.toString() + ' model'
      + pluralSuffix( n ) + dotOrColon( n );

    $('<p/>').text( prompt ).appendTo('#content');
  }
);

As you can see, the db.getView method is provided with three arguments: the database name, the view name, and a call-back function.

Understanding how the call-back function works was another big stumbling block for me.

In this simple case, all is clear, of course.

We submit the query to get the view and return immediately.

CouchDB processes the request and invokes the call-back function when completed.

The call-back function processes the resulting data rows, extracting the model document data from the key provided with each row and populating the HTML scaffolding accordingly.

Again, here is the final result with two models listed, just as you can see in the video above:

Well, I am spending much too much time documenting this for you, and really need to get on with the implementation and my real day work, so I will call it wraps for today now.

Room Editor Project Overview and CouchDB Configuration

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, here are some issues I tackled since my last report:

• Project Overview
• Replicating a CouchDB with Python
• Same origin policy snag and resolution
• Learning and struggling with CouchApps
• Relief moving to Kanso
• Next steps

Project Overview

To recapitulate, the grand plan is to grab a 2D floor plan with furniture and equipment layout from the BIM, upload it to the cloud, and make it accessible for viewing on mobile devices:

Furthermore, I am enabling some simple editing operations on the mobile device, e.g. to move the furniture and equipment around in the room a bit, update the cloud-based data repository, and reflect these changes back into the desktop BIM:

All of this with absolutely nil installation on the mobile device, and thus totally ubiquitous, using SVG and server-side scripting.

I already addressed a number of issues in realising this project and am documenting my progress here on the blog, in the three categories desktop, cloud and mobile.

Here is an overview of the results presented so far, both for this project and some previous related topics, classified into those three categories:

• Project overview and Tech Summit proposal
• Desktop
• Room plan view boundary loops
• Sort and orient curves to form a contiguous loop
• Extrusion analyser and plan view boundaries
• Curve following face and bounding box implementation
• GeoSnoop boundary curve loop visualisation
• Desktop to cloud via DreamSeat CouchDB Client
• Cloud
• Getting Going with the Cloud
• Apollonian Sphere Packing Web Service and AVF
• The BIM 360 Glue Viewer and REST API
• BIM 360 Glue REST API Authentication Using Python
• Free Cloud Based Data Repository with NoSQL, CouchDB, and IrisCouch
• Mobile
• Testing my OBJ exporter on Android
• Mobile Device Room Location
• Room Polygon and Furniture Picker in SVG
• 2D SVG Editing on Mobile Device with Raphael

Replicating a CouchDB with Python

In my last step, I determined the room, furniture and equipment plan view boundary polygons and uploaded them to a CouchDB database in the cloud, hosted on IrisCouch.

To play around interactively with that data, I would prefer to store it locally instead of on the server.

The easiest way to achieve this is to replicate the database.

Replicating a CouchDB repository is trivial, since it has built-in support for that.

All you need to do is specify the source and target database name and URL.

Also, as you may know, I love Python for command-line scripting.

Happily, several CouchDB interfaces for Python are available. As you can see on that page, they can be pretty simple.

Couchdbkit seems well supported and does the job.

Here is a little Python script that replicates the database 'rooms' created by my Revit add-in in IrisCouch from the web to a new database 'rooms2' my local CouchDB installation:

#!/usr/bin/python
import couchdb

server = couchdb.Server()
server.create( 'rooms2' )
server.replicate(
  'http://jt.iriscouch.com/rooms',
  'rooms2' )

You cannot make it much shorter or simpler than that, can you?

Same Origin Policy Snag and Resolution

I was originally envisioning a simple architecture composed of three components on the desktop, in the cloud, and on the mobile device, respectively, as illustrated above.

I started looking at how to access the cloud-based data repository from the mobile device and closed my last foray into this area mentioning that I had a nasty surprise discovering that the strict same origin policy prevents my simple JavaScript application from accessing my IrisCouch domain, so I cannot easily read the data on the mobile device in the manner I had expected.

The discovery cost me a few grey hairs and some sleep, but I found a good and obvious solution for that which you are probably all aware of already: server-side scripting.

In fact, this even simplifies things, in the end, since I really have nothing at all to install or implement on the mobile device, and my list of components to implement is reduced from three to two. Ok, it adds some complication to the cloud stuff, of course... or actually just additional learning opportunities.

I had already decided that NoSQL and the CouchDB implementation look like good candidates for my data repository requirements, and that I can test and host them in the cloud for free using the IrisCouch server. Please refer to the link in the overview above for more info on these.

Happily, CouchDB offers full support for server-side scripting. The same-origin policy effectively requires that the HTML from which the JavaScript is loaded must be served up from CouchDB. This can be done by attaching an HTML document to a CouchDB document. You can do this manually, or through the use of CouchApps.

Learning and Struggling with CouchApps

CouchApps are CouchDB generation environments and tools for web application developers interested in creating database-driven applications using nothing but HTML, CSS, and JavaScript.

A CouchApp is simply a collection of files that completely defines a CouchDB database to simplify development, deployment and maintenance. Simple command-line tools are used to synchronise the file collection with the real live CouchDB implementation.

I dived into several of the numerous CouchApp tutorials and was so excited I ended up spending entire nights at it, once with no sleep at all.

Here are some of the things I looked at:

• Getting started
• Build a simple CouchApp
• Good IBM CouchApp tutorial
• A short and effective CouchApp and JavaScript tutorial
• A better introduction and some more modern alternatives
• Documentation for jquery.couch.js
• A very clear and impressive CouchApp video tutorial by Max Ogden
• Very impressive node CouchApp JavaScript library node.couchapp.js
• Using node.js for effective asynchronous processing
• node.js + CouchDB == Crazy Delicious video presentation

Unfortunately, I found it pretty confusing. I learned a huge amount and achieved very little, partly due to the fact that several different CouchApp implementations exist and are used in parallel, and the tutorials do not specify exactly which version they are based on.

Still, I learned enough to continue feeling very enthusiastic about this approach, and then found an easier solution.

Relief Moving to Kanso

After struggling with different CouchApp implementations, I discovered Kanso, toting itself "the best way to create and share apps on CouchDB".

With the little that I know so far, I fully agree with that. Apparently, kanso is the Japanese phrase for simplicity, or, more specifically, simplifying the complex.

So easy! Everything works! The documentation includes a short and succinct getting started tutorial that explains a lot.

Later I found another tutorial that goes further faster than the one included in the documentation pages.

Later still, I found this extremely well documented complete application that can be tested online and demonstrates numerous additional important new features.

After studying these samples and trying to reuse some of the powerful functionality they provide, I am returning more and more often to the Definite Guide for CouchDB and finally starting to understand the basics of view, show and list functions, etc.

Bit by bit, I am managing to get some SVG graphics to display in my server-side scripts. Making use of the Raphael library, as I was planning to do, may prove hard, since there is no ready-built Kanso package for it. I may therefore revert to implementing my room furniture placement editor in pure SVG instead.

Next Steps

My next steps will be:

• Separation of symbol and instance data in my add-in and database structure: currently, the furniture loops are placed absolutely, and multiple instances of a symbol duplicate the same loop over and over again at different locations. I will rewrite this to separate the furniture loop definition, defined by the family symbol, and its placement, defined by the instance. This needs to be done anyway to enable editing the placement data through the editor interaction on the mobile device.
• Learn how to use templates in Kanso.
• Implement server-side generated SVG code to display the room and furniture plan in CouchDB using Kanso.
• Implement editing of SVG on the mobile device and reflect changes back to CouchDB (I do not know how yet).
• Implement Idling event handler and polling of CouchDB in the desktop add-in to reflect the changes back to the BIM in real-time.
• Implement an external application wrapper for the add-in providing four commands:
• Upload to cloud
• Refresh from cloud
• Subscribe to cloud
• Unsubscribe from cloud

I know exactly how to address all these points now, except for reflecting back the SVG editor changes to the CouchDB.

I remain excited and optimistic and look forward to hearing your comments and suggestions.

Desktop to Cloud via DreamSeat CouchDB Client

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I now started looking at storing the plan view room and furniture boundary loop data in the cloud.

I wound up the main Revit add-in functionality using the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances, sort and orient its output curves, determine their bounding box and visualise the results in a dynamically generated GeoSnoop .NET form for verification. The plan view boundary loop data is handily managed in integer-based 2D points packaged by the JtLoops class.

That wraps up the initial add-in implementation. We will certainly return to it and add more functionality when the time comes to update the model with the edits applied on the mobile device.

Moving to the Cloud

The next step is to implement a cloud-based data repository to make this information ubiquitously available for consumption on mobile devices and elsewhere.

I mentioned looking at the CouchDB database and the free IrisCouch hosting service as a candidate repository implementation.

My colleague Philippe Leefsma took that same thought and very quickly and easily implemented a simple and efficient restful database using those components to host and consume images of CAD model data.

Philippe used the DreamSeat .NET CouchDB wrapper library to easily access the functionality from within a .NET add-in.

He added his own asynchronous support, in addition to the asynchronous support already provided by DreamSeat itself, and attached the complete implementation of a .NET client and console allowing for upload and viewing of pictures.

I added DreamSeat support to feed a CouchDB database with my plan view room and equipment boundary loop data in just a very few simple steps:

• Implement SVG path properties
• Add references to the DreamSeat libraries
• Implement couch document wrappers
• Instantiate, populate and save to cloud
• Looking at the cloud-based data repository

Implement SVG Path Properties

First of all, I need to decide how to store the boundary loops in my data repository.

I initially thought I would save the integer values, and may still do so.

For the moment, though, I implemented a much simpler placeholder by adding methods to the point and loop classes to serialise the data to a single complete SVG path string representation.

A single string is easy to add to the database and can be reused directly for the SVG visualisation. I am not planning to modify the boundary loops in any way, so I might as well manage them in static strings. The only disadvantage would be if I wanted to scale the coordinates differently. If that need arises, I may switch to uploading the structured integer-based point and loop data instead. We'll cross that bridge when we come to it.

An SVG path element contains a path data attribute that can include moveto, line, curve, arc and closepath instructions.

For an individual point, I simply output its two coordinate values. For the first loop vertex, I prepend an 'M' for moveto. For the second one, I prepend an 'L' for line-to. For all following vertices, the 'L' can be omitted. At the end, a 'Z' is appended to close the path.

For an individual point, Point2dInt, the SvgPath property is therefore implemented like this:

  /// <summary>
  /// Return a string suitable for use in an SVG 
  /// path. For index i == 0, prefix with 'M', for
  /// i == 1 with 'L', and otherwise with nothing.
  /// </summary>
  public string SvgPath( int i )
  {
    return string.Format( "{0}{1} {2}",
      ( 0 == i ? "M" : ( 1 == i ? "L" : "" ) ),
      X, Y );
  }

For an individual boundary loop, JtLoop, the member vertices are converted to their SVG string representation using LINQ and concatenated using the string Join method:

  /// <summary>
  /// Return an SVG path specification, c.f.
  /// http://www.w3.org/TR/SVG/paths.html
  /// M [0] L [1] [2] ... [n-1] Z
  /// </summary>
  public string SvgPath
  {
    get
    {
      return string.Join( " ",
        this.Select<Point2dInt,string>(
          (p,i) => p.SvgPath( i ) ) )
        + "Z";
    }
  }

For a collection of loops, JtLoops, concatenate the individual loop paths:

  /// <summary>
  /// Return the concatenated SVG path 
  /// specifications for all the loops.
  /// </summary>
  public string SvgPath
  {
    get
    {
      return string.Join( " ",
        this.Select<JtLoop,string>(
          a => a.SvgPath ) );
    }
  }

With these properties in place, I can finally set about uploading the data to the cloud.

Add References to the DreamSeat Libraries

Just like Philippe, I use the DreamSeat wrapper to access the CouchDB functionality from my .NET Revit add-in.

I simply added this functionality to the existing GetLoops external command.

First, I need to reference the DreamSeat .NET assemblies to access it classes and methods.

I grabbed these from the DreamSeat sample solution on github.

For my initial minimal upload usage, all I need are DreamSeat.dll and mindtouch.dream.dll:

Implement Couch Document Wrappers for my Data

Data in CouchDB is stored in documents.

DreamSeat provides a CouchDocument base class for deriving your own document wrappers.

I implemented derived classes to store some minimal model, level, room and furniture data as follows:

class DbObj : CouchDocument
{
  protected DbObj()
  {
    Type = "obj";
  }
  public string Type { get; protected set; }
  //public string UniqueId { get; set; }
  public string Description { get; set; }
  public string Name { get; set; }
}
 
class DbModel : DbObj
{
  public DbModel()
  {
    Type = "model";
  }
}
 
class DbLevel : DbObj
{
  public DbLevel()
  {
    Type = "level";
  }
  public string ModelId { get; set; }
 
}
 
class DbRoom : DbObj
{
  public DbRoom()
  {
    Type = "room";
  }
  public string LevelId { get; set; }
  public string Loops { get; set; }
}
 
class DbFurniture : DbObj
{
  public DbFurniture()
  {
    Type = "furniture";
  }
  public string RoomId { get; set; }
  public string Loop { get; set; }
  public string Transform { get; set; }
}

I initially thought of identifying documents with the auto-generated CouchDB identifiers, but then chose to use the UniqueId already provided by Revit to identify the objects in CouchDB as well.

Type, description and name are fields added to all my objects.

Type identifies the object type and can be one of model, level, room or furniture.

The only information of interest to me is:

• Mutual relationships, i.e. which room belongs to what level, where does the furniture go, etc., handled by the ModelId, LevelId and RoomId properties.
• Boundary loop data for display purposes, currently stored as strings representing the SVG path information produced by the properties described above.
• The transform applied to the furniture, which can be moved and rotated in the mobile device room editor and then needs to be updated back to the model again.

Pretty minimal and readable, isn't it?

Instantiate, Populate and Save to Cloud

Here is the entire code to connect to the cloud database host, open the 'rooms' database, and populate the room and furniture data for a given room, either creating new records or updating existing ones:

void UploadRoom(
  Room room,
  List<Element> furniture,
  JtLoops roomLoops,
  JtLoops furnitureLoops )
{
  CouchClient client = new CouchClient(
    "jt.iriscouch.com", 5984 );
 
  CouchDatabase db = client.GetDatabase(
    "rooms", true );
 
  string uid = room.UniqueId;
 
  DbRoom dbRoom;
 
  if( db.DocumentExists( uid ) )
  {
    dbRoom = db.GetDocument<DbRoom>( uid );
 
    Debug.Assert(
      dbRoom.Id.Equals( room.UniqueId ),
      "expected equal ids" );
 
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = room.Level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
 
    dbRoom = db.UpdateDocument<DbRoom>( dbRoom );
  }
  else
  {
    dbRoom = new DbRoom();
 
    dbRoom.Id = uid;
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = room.Level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom = db.CreateDocument<DbRoom>( dbRoom );
  }
 
  int i = 0;
 
  foreach( Element f in furniture )
  {
    uid = f.UniqueId;
    if( db.DocumentExists( uid ) )
    {
      DbFurniture dbf = db.GetDocument<DbFurniture>(
        uid );
 
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.Loop = furnitureLoops[i++].SvgPath;
      dbf = db.UpdateDocument<DbFurniture>( dbf );
    }
    else
    {
      DbFurniture dbf = new DbFurniture();
      dbf.Id = f.UniqueId;
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.Loop = furnitureLoops[i++].SvgPath;
      dbf = db.CreateDocument<DbFurniture>( dbf );
    }
  }
}

As you can see, I am storing the data in my IrisCouch hosted database in the cloud.

Looking at the Cloud-based Data Repository

After running this command, I can retrieve the top-level database information in JSON format:

{"db_name":"rooms", "doc_count":10, "doc_del_count":11,
"update_seq":54, "purge_seq":0, "compact_running":false,
"disk_size":102511, "data_size":6921,
"instance_start_time":"1365674085202773",
"disk_format_version":6, "committed_update_seq":54}

This is what an individual room looks like in futon, the CouchDB management console:

Here is the raw JSON representation of the same data:

{
  "_id": "4d2e6fd6-eb44-4e2a-98c5-271decaa9225-00033e9f",
  "_rev": "2-a863fbc7b2294ef4d8630bc961221b24",
  "levelId": "e3e052f9-0156-11d5-9301-0000863f27ad-00000137",
  "loops": "M2753 3087 L-4446 3087 -4446 587 -746 587 -746 -1212 2753 -1212Z M298 -112 L298 587 1698 587 1698 -112Z",
  "type": "room",
  "description": "Room Rooms <212639 Room 1>",
  "name": "Room 1"
}

So far, so good.

Once I got that far, I wanted to start working on the visualisation in SVG and had a very nasty surprise: the strict same origin policy prevents my simple JavaScript application from accessing my IrisCouch domain, so I cannot easily read the data.

The discovery robbed me of a full night's sleep, but I think I have found a good way out of that dilemma as well.

Wish me luck!

Cloud-Based Restaurant Seating and Cleaning

I hope you had a successful Easter egg hunt.

As you probably noticed, I have lately been focusing on the research and implementation of my cloud-based round-trip 2D Revit model editing project for the upcoming Autodesk internal tech summit in June as much as my day-to-day tasks will allow.

Current Project Overview

To recap, the basic idea is simple: implement an example of round-trip minimal simple editing of a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser.

To keep the editing task as minimal and simple as possible, I just envision changing the 2D location and orientation of the furniture and equipment within the boundaries of the selected room.

Such an editor can be realised on any mobile device using JavaScript and SVG, scalable vector graphics, as I showed in my prototype room polygon editor using the Raphaël JavaScript SVG library:

Room layout editor

Aside from the editing component, this workflow will also require:

• A cloud-based database repository managing the Revit model, level, room, furniture and equipment data.
• A Revit add-in retrieving the data from the Revit project and populating the data repository.

The data repository is fed from the Revit model and queried by the mobile device editor. It also manages changes to the furniture and equipment location and orientation.

The editor displays the room, furniture and equipment and enables translation and rotation of the latter, which updates the repository data.

The Revit add-in can optionally be expanded to automatically query and update the Revit model based on new furniture and equipment locations, resulting in the following workflow:

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents in a 2D rendering on any mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Pick up and display the modified model in Revit.

I already discussed my current candidate for the cloud database using the CouchDB NoSQL database implementation and IrisCouch free hosting service.

Regarding the Revit add-in retrieving the room and furniture 2D boundary polygons, I also looked at the retrieval of plan view room boundary loops and family instances in a given room.

Next steps will include enhancing the Revit add-in to extract suitable boundary loops to represent the furniture and equipment in the mobile editor, and above all the data repository implementation.

Project Expansion for Cloud-Based Restaurant Seating and Cleaning

As a very happy surprise, I now found a beta site to test the existing functionality and add even more, by hooking up the mobile device furniture layout editing functionality with a restaurant cash register to implement a fully automated restaurant seating layout and floor cleaning system.

The basic idea is to equip the restaurant furniture with unobtrusive mobility support and link the virtual model of the restaurant and its furniture with the real-world objects.

All that is required to provide real-world control over the furniture position are concealed wheels and locking devices inside the table base. The wheels are normally locked in position, and their existence goes unnoticed. They can be unlocked and driven by motors for displacement.

The entire restaurant layout can thus be rearranged via the 2D layout editor on the mobile device, with no manual intervention whatsoever required.

Each piece of furniture also includes location detection support. Besides the automatic rearrangement triggered by updating the virtual model, the inverse is also supported: moving the furniture around manually can trigger the virtual model to be updated instead to reflect the new real-world positions.

Here is a snapshot of the restaurant cash register showing the original layout before editing:

The cash register lives in the pillar in the centre of the restaurant. The pillar is not displayed on the cash register screen snapshot above:

The bar in the corner is marked in red on the screen snapshot, and its position cannot be edited:

Rotating and moving the tables in SVG triggers the synchronisation chain and drives the real-world furniture to its new position:

As you can see, the table base looks completely normal and can easily contain the required motors, wheels, locking and location devices:

Fully Automated Restaurant Cleaning

Mobile autonomous furniture obviously also vastly facilitates the restaurant cleaning.

The furniture is programmed to flock together at one end of the room each night, making space for a cleaning robot to roam freely, and moves over to the other end of the room after the first half has been covered.

This obviously enables much more effective and thorough cleaning than if the furniture is left in place:

It is fascinating to see BIM expanding into new hitherto unexpected areas, and unbelievably exciting to participate in the process!

I trust you will find similar opportunities to embrace this paradigm and successfully use the Revit API to support expanding your applications and ideas into other new niches.

I am looking forward to keeping you posted on the further progress of this ongoing project!

JavaScript Physics Sample

By the way, talking about new niches and programming in and for the cloud, here is an utterly cool JavaScript physics sample.

It provides an incredibly compelling and sheer unbelievably compact example use of HTML5, Canvas, CSS and JavaScript for an interactive graphical physical simulation in just three hundred lines of code.

Relax – Simple Free Cloud Based Data Repository with NoSQL, CouchDB, and IrisCouch

Last week, I mentioned my proposal for the Autodesk Technical Summit in June, to present a cloud-based round-trip 2D Revit model editing project.

That will obviously required a cloud-based data repository. Talking with my colleagues, all of their suggestions were oriented towards the Microsoft Azure and Amazon solutions discussed so far on the cloud and mobile DevBlog.

I was searching for something freer, more open source, and less proprietary, and was rather surprised to discover an utterly relaxing solution that so far looks absolutely perfect for me and my needs.

I first stumbled upon IrisCouch, which led me to CouchDB and NoSQL, which all make me very happy. For didactical purposes, I will discuss them in inverted order, though.

Before I get to that, I would also like to mention my first ski tour of the year:

• Ski Tour Season Opening
• NoSQL
• CouchDB
• IrisCouch
• ID and GUID in Revit Documents
• Visual Revit Programming with Dynamo

My Ski Tour Season Opening

I went on a ski crossing of the Glarner Alps last weekend.

We took the cable lift up to the Fisetenpass and climbed the Gemsfairenstock, Clariden and Piz Cazarauls. We were hoping to get on to the Schärhorn as well, but had to give that up due to bad weather conditions. Instead we headed over the glacier to the Chammlijoch und down the Iiswaendli back to the Klausenpass.

This was my second ascent of the Clariden Mountain, following the last one in September 2011, from the opposite direction and obviously under very different conditions.

A great way to get away from computers for a day or two and face the natural elements instead, at their wildest and fiercest.

Relax – with NoSQL

As said, researching a simple efficient cloud-based data repository for my SVG editing project, I discovered NoSQL, 'not only SQL', a whole new class of database model, hitherto unknown to me.

A NoSQL database provides a simple, lightweight mechanism for storage and retrieval of data that provides higher scalability and availability than traditional relational databases. The NoSQL data stores use looser consistency models to achieve horizontal scaling and higher availability. Some NoSQL systems do allow SQL-like query language to be used.

NoSQL database systems are often highly optimized for retrieval and appending operations and often offer little functionality beyond record storage, e.g. key–value stores. The reduced run-time flexibility compared to full SQL RDBM systems is compensated by marked gains in scalability and performance for certain data models.

Since my application will only require storage of simple key-value pairs and should in theory be massively scalable, this sounds like an optimal choice. In practice, I only expect it to be a toy, of course; the scalability is required only to make it a useful example toy.

Relax – with CouchDB

Apache CouchDB is a NoSQL implementation, one of a new breed of database management systems.

As stated by its official by-line, the one word to describe CouchDB is relax. When you start CouchDB, you see:

Apache CouchDB has started. Time to relax.

CouchDB is built not only for, but of the Web. Its design borrows heavily from web architecture and the concepts of resources, methods, and representations. Data is self-contained:

Replication and backup is extremely simple, basically requiring no more than a modification of the base URL.

CouchDB is implemented in the Erlang programming language, which is used to build massively scalable soft real-time systems with requirements on high availability with uses in telecommunication, banking, e-commerce, computer telephony and instant messaging. Erlang's runtime system has built-in support for concurrency, distribution and fault tolerance.

Here is a 'what is' Q&A, getting started tutorial and full 270-page O'Reilly textbook CouchDB – The Definite Guide.

The textbook samples make use of the cURL command line tool, e.g. the following two command line statements to create a new and list a database:

  curl -X PUT http://127.0.0.1:5984/baseball
  {"ok":true}

  curl -X GET http://127.0.0.1:5984/_all_dbs
  ["baseball"]

Relax – with IrisCouch

As I initially mentioned, the starting point of this exploration of mine was IrisCouch, which terms itself 'easy CouchDB'. It provides a free hosting service, 'a couch in the cloud'. You can sign up in minutes to have your own Apache CouchDB server.

For my purposes, I can install CouchDB on my local machine, develop my data repository locally, and push it all to the cloud by replicating my local database to IrisCouch and changing the base URL to use that for all interaction.

Relax – with DreamSeat

While I explored the theory, my colleague Philippe Leefsma went ahead and implemented a pair of .NET applications uploading and consuming cloud-based data from an IrisCouch-hosted CouchDB database using the DreamSeat CouchDB .NET wrapper library.

Although the DreamSeat documentation boasts support for both complete synchronous and asynchronous API, Philippe used Visual Studio 2012 and its .NET 4.5 async support that automatically and transparently implements the entire support for async call-back. 'Async' methods can use the 'await' keyword, so he wrote a couple of anync wrapper methods for standard synchronous DreamSeat calls.

Well, that provides lots of material to play with in the immediate future, and gives me hope of easily implementing my cloud-based data repository requirements.

Here are a couple of other more directly Revit API related notes:

ID and GUID in Revit Documents

Question: A short question about the way unique ID’s are managed in Revit. I want to export a large number of RVT models through DB link to a single database and I really need to have unique ID’s in my destination tables. So far what I’ve seen is that the records pushed to my database have a field ID which seems to be unique within each Revit file, but not with my set of files.

So is there a way to have really unique identifier like a GUID instead of simple ID in my RVT models? Or at least is there a way to rely on a kind of GUID when we push data through DB link?

Answer: Each Revit element has an ID property, its element id, which is unique within the RVT document, but not globally.

Each Revit element also has a UniqueId property, which is globally unique, unless you do something to sabotage that.

Under normal circumstances, the UniqueId should fulfil your needs.

Visual Revit Programming with Dynamo

One last, final note before closing: if you are interested in a visual programming environment for Revit which allows non-programmers to create workflows to automate Revit functionality and geometry creation, be sure to check out Dynamo, also featured at AutodeskVasari.com.

Cloud & Mobile, Extensible Storage Data Use in Schedules

My topics for today are:

• Cloud and mobile topics I covered so far
• Cloud-based round-trip 2D Revit model editing on any mobile device using SVG
• Extensible storage data use in schedules

I am still meeting with my European DevTech colleagues here in Konk Leon, 'anse du Lèon', the cove of the lion, aka Le Conquet, Brittany.

Yesterday, one of our topics was work we have done so far for cloud and mobile applications. It was very interesting to hear about my peers' rich and varied experiences.

Cloud and Mobile Topics Covered so Far

I documented all my own experiences so far here on the blog, and was able to reuse that for my presentation quite spontaneously with no further preparation:

• Accessing a REST API web service from a Revit .NET add-in – Apollonian sphere packing and AVF.
• Thoughts on mobile indoor positioning, representing room polygons in SVG, the Azure SDK, ASP.NET MVC 4, and implementing a web service.
• An overview of the BIM 360 Glue viewer and REST API.
• BIM 360 Glue REST API authentication using Python.
• A room polygon and furniture picker in SVG.
• 2D SVG editing on mobile devices using the Raphaël JavaScript SVG library.

As I explained at the time, all of the explorations involving SVG are part of a larger master plan.

This plan has now matured to a certain extent and is forcing me to move ahead quite fast in the immediate future.

The main outcome so far is a presentation proposal that I submitted for the internal Autodesk technical summit taking place in June, and the fact that it was accepted.

My cloud and mobile roadmap is thus now clearly focused on implementing that proposal:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device using SVG

I described the roadmap I envision in the discussion of my simple SVG editor. The main components include:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• The SVG editor running in a browser on any device, rendering the model and supporting some simple geometric modification.

Here is the actual wording of my technical summit proposal:

Proposal Abstract

This presentation demonstrates round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser. How can this be achieved? A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository. On the mobile device, the repository is queried and the data is rendered in a standard browser using JavaScript and SVG. The rendering supports modification, such as translation and rotation of the furniture and equipment, which is saved back to the cloud database. The Revit add-in picks up these changes and updates the Revit model.

Intended Audience and Prerequisites

Intended audience is programmers with interest in cloud-based and mobile computing, specifically interest in round-trip editing of a Revit model using a cloud-based data repository and editing a 2D model on an arbitrary mobile device with no additional software beyond a browser installed on it. 
Knowledge of .NET, JavaScript and REST programming is helpful but not required. Revit add-in experience is not a prerequisite.

Presentation Outline

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Pick up and display the modified model in Revit.

Two of the important components whose implementation I plan to explore next are the polygon generation and data model:

Plan View Polygon Determination

The generation of the room boundary polygons is obvious, since the room has a boundary property.

For the furniture and equipment family instance, the solution is a less immediate. My current idea is to explore making use of the ExtrusionAnalyzer class. It is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction. As far as I can tell, that should be exactly what I need.

Scott Conover mentioned this class in his session on the Geometry API, a continuation of his AU 2011 presentation CP4011 'Geometric Progression: Further Analysis of Geometry Using the Autodesk Revit 2012 API', enhanced for the Revit 2013 API.

As soon as I have the polygons determined, I want to implement functionality to render them easily. This will involve extent calculation, canvas definition, and coordinate system transformation. I will probably implement a simple .NET geometry viewer before moving on to the SVG rendering. I've been wanting to do that for a long time...

Cloud-based Data Repository

So far, my colleagues have been focusing on using the Amazon and Azure cloud hosting services, and many discussions on the cloud and mobile DevBlog deal with them.

I searched the Internet for other cloud-based database alternatives, and right now CouchDB looks pretty promising, so I might try a completely different approach using that instead.

There is a lot to do here as well: define the data model, set up the web service, define a format for saving the polygon data, etc. At the very least, I will need to manage:

• Model > metadata, rooms.
• Room > metadata, model, furniture, level, polygon.
• Furniture > metadata, room, polygon, transformation (initially identity).

Round tripping the information will be interesting, especially if I want the Revit model to update automatically when furniture positions are modified on the mobile device, which I certainly do, if only for the wow effect :-)

Stay tuned...

... Oh, and, yeah, wish me luck!

Extensible Storage Data Use in Schedules

Returning to the desktop again, here is a recent question from a developer on using estorage data in a schedule that leads to some general observations on that topic:

Question: I would like to display my extensible storage information in a schedule. I searched high and low, though, and was unable to find any samples or documentation on the subject. Can you help?

Answer: There is a good reason why you have not found anything: there is no such support.

The usage of extensible storage data is utterly and completely up to the add-in itself. The Revit API offers no support whatsoever for making use of estorage data in any way. The only support provided is for storage and retrieval, nothing else.

Well, one tiny little detail more: if an element id value is stored, and the element id is later modified by some worksharing operation, its value will be automatically updated.

On the other hand, there is currently no direct support for putting data into a schedule either.

I am no user interface expert, but I think that you can set up a schedule to be populated from certain parameter values via the user interface. You would have to talk with an application engineer or product support or explore this topic on the Internet to find out how that can be done.

Of course, there is nothing stopping you from extracting your data from extensible storage and transferring it into parameters set up to populate a schedule yourself.

I hope that answers your question and helps you get started successfully.

2D SVG Editing on Mobile Device with Raphaël

As I mentioned last week, I took another look at displaying a 2D view of a Revit model on mobile devices using SVG to enhance the room polygon and furniture picker in SVG.

That implementation displays a read-only view of the model, useful for picking and identifying elements, e.g. for querying or adding metadata to them.

It would also be nice to be able to edit some data graphically, e.g. enable translation and rotation of the furniture and other family instances.

The long-term goal is to implement a cloud-based round-trip 2D Revit model editing on any mobile device using SVG.

The advantage of SVG is that it enables display and edit of a 2D scene, e.g. a rendering of a Revit model, on any mobile device with no need for installation of any additional software whatsoever beyond a browser.

The parts that I still want to explore include a Revit add-in to export polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository, and querying the repository from the mobile device.

To simplify editing the model, I wrapped all the SVG interaction in a JavaScript library.

After some research and comparison of different available open source SVG libraries and editors, I chose the Raphaël JavaScript library. I then worked through the following series of incremental implementation steps to first recreate the state I had already achieved previously, then add drag, rotate, and button support:

1. Curves
2. Grid
3. Room
4. Reporting text and click handler
5. Furniture
6. Drag
7. Rotate
8. Button
9. Conclusion

To immediately jump into my testing playground, you can simply access The Building Coder SVG folder.

The Raphaël JavaScript Library

Raphaël ['ræfeɪəl] is a small JavaScript library that simplifies work with vector graphics on the web.

Raphaël uses the SVG W3C Recommendation and VML as a base for creating graphics. This means every graphical object is also a DOM object, so JavaScript event handlers can be attached and the objects can be dynamically modified. The stated goal is to provide an adapter to make drawing vector art compatible cross-browser and easy.

Raphaël supports the current versions of Firefox, Safari, Chrome, Opera and Internet Explorer.

Curves

The first step I took was to extract one of the Raphaël demo pages, curver.html, and host it on my own page to ensure that it has no other dependencies and continues to work in my environment:

Curves

It shows how curves can be drawn and hooked up with event handlers to react to dragging.

To explore this or any other of the Raphaël demo implementations, simply navigate to it and view the source.

Grid

Once I had that in place and up and running, my next steps dealt with reimplementing the state of the existing pure SVG equipment picker using Raphaël instead.

The first step is easy, simply setting up the canvas and a rectangular grid:

Grid

Here is the source code HTML achieving this (copy to a text editor or view source to see the truncated lines in full):

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=ascii">
    <title>Jeremy's 2D Mobile Device Revit Model Editor Grid</title>
    <link rel="stylesheet" href="demo.css" type="text/css" media="screen">
    <link rel="stylesheet" href="demo-print.css" type="text/css" media="print">
    <script src="raphael-min-jt.js" type="text/javascript" charset="ascii"></script>
    <script type="text/javascript" charset="ascii">
      window.onload = function () {
        var w = 600, h = 400;
        var r = Raphael("holder", w, h);
        --w;
        --h;
        r.rect(0, 0, w, h, 10).attr({stroke: "#666"});
        // grid
        var d = 50, i;
        for (i = d; i < h; i += d) {
          r.path([[ "M", 0, i], ["L", w, i]]).attr({stroke: "#666"});
        }
        for (i = 50; i < 600; i += 50) {
          r.path([["M", i, 0], ["L", i, w]]).attr({stroke: "#666"});
        }
      };
    </script>
  </head>
  <body>
    <div id="holder"></div>
    <p id="copy">Jeremy Tammik, Autodesk Inc. using the <a href="http://raphaeljs.com">Raphael</a> JavaScript vector library</p>
  </body>
</html>

Room Polygon

Next, display the static room polygon on the grid:

Room

Basically, we simply add the following line of code:

  // room - outer loop anti-clockwise, inner clockwise

  r.path("M 40 40 L 440 40 440 300 300 300 300 200 40 200"
    + " Z M 320 240 L 320 280 420 280 420 240 Z")
    .attr({stroke: "blue", fill:"lightblue"});

There are several different ways to implement the hole. Note that the oddeven fill rule is applied by default and requires strict adherence to the clockwise and anti-clockwise orientation of loop vertices. I found the hints on how to achieve donut holes with paths useful.

Reporting Text and Click Handler

The main feature of the original furniture picker was the identification and dynamic reporting of the room polygon, furniture, or equipment picked on screen. The reporting function could of course be expanded to display or edit any other information desired, including updating some repository with modified data.

Text

To achieve this in the Raphaël environment, I implemented a JavaScript event handler:

  jOnClick = function () {
    var s = "Id " + this.id.toString()
      + ": " + this.data("jid");
    t.attr({text:s});
  }

The clicked object is displayed using a new text element, and both the background rectangle and the room polygon are assigned a 'jid' identifier and subscribe to the click event to trigger the event handler:

  // room - outer loop anti-clockwise, inner clockwise

  var room = r
    .path("M 40 40 L 440 40 440 300 300 300 300 200 40 200 Z"
      + "M 320 240 L 320 280 420 280 420 240 Z")
    .attr({stroke: "blue", fill:"lightblue"})
    .data("jid", "room")
    .click(jOnClick);

  // reporting text

  var t = r
    .text(300, 380, "Welcome. Please click around.")
    .attr({stroke: "#fff"});

Furniture and Equipment

Next, I added the furniture, consisting of table and chair placeholders:

Each one is implemented similarly to the room polygon, equipped with its own identifier, and obviously subscribing to the click event:

  // furniture

  r.rect(100, 100, 200, 40, 5)
    .attr({stroke: "blue", fill:"blue"})
    .data("jid", "table")
    .click(jOnClick);

  r.rect(75, 110, 16, 22, 5)
    .attr({stroke: "blue", fill:"blue"})
    .data("jid", "chair1")
    .click(jOnClick);

  r.rect(118, 150, 22, 16, 5)
    .attr({stroke: "blue", fill:"blue"})
    .data("jid", "chair2")
    .click(jOnClick);

  r.rect(158, 150, 22, 16, 5)
    .attr({stroke: "blue", fill:"blue"})
    .data("jid", "chair3")
    .click(jOnClick);

  r.rect(198, 150, 22, 16, 5)
    .attr({stroke: "blue", fill:"blue"})
    .data("jid", "chair4")
    .click(jOnClick);

  r.rect(238, 150, 22, 16, 5)
    .attr({stroke: "blue", fill:"blue"})
    .data("jid", "chair5")
    .click(jOnClick);

With that, we have arrived at the same stage of functionality as we already had using just pure SVG with no additional toolkit support. Now comes the new fun stuff.

Drag

Raphaël supports dragging. Here, the furniture has been dragged away from its original locations:

Drag

Drag event subscription requires event handlers for the drag initialisation, move and mouse up actions:

  // drag support

  var dragger = function () {
    this.ox = this.type == "rect" ? this.attr("x") : this.attr("cx");
    this.oy = this.type == "rect" ? this.attr("y") : this.attr("cy");
    this.animate({"fill-opacity": .5}, 500);
  },
  move = function (dx, dy) {
    var att = this.type == "rect"
      ? {x: this.ox + dx, y: this.oy + dy}
      : {cx: this.ox + dx, cy: this.oy + dy};
    this.attr(att);
    r.safari();
  },
  up = function () {
    this.animate({"fill-opacity": 1}, 500);
  },

To subscribe to the drag event efficiently, I reimplemented the furniture as an array that I can iterate over uniformly:

  // furniture

  furniture = [
    r.rect(100, 100, 200, 40, 5).data("jid", "table"),
    r.rect(75, 110, 16, 22, 5).data("jid", "chair1"),
    r.rect(118, 150, 22, 16, 5).data("jid", "chair2"),
    r.rect(158, 150, 22, 16, 5).data("jid", "chair3"),
    r.rect(198, 150, 22, 16, 5).data("jid", "chair4"),
    r.rect(238, 150, 22, 16, 5).data("jid", "chair5")
  ];

  var n = furniture.length;

  for (i = 0; i < n; ++i) {
    furniture[i].attr({stroke: "blue", fill:"blue"})
      .click(jOnClick)
      .drag(move, dragger, up);
  }

Rotate

I fiddled around for a while to implement the rotation. Here is some dragged and rotated furniture:

Rotate

In order to handle dragging, I ended up implementing a text element that triggers a rotation of the currently selected element. A sibling text element reverses the rotation, i.e. rotates counter-clockwise.

The Raphaël rotation handling seems somewhat controversial, as far as I can tell from numerous discussions on the topic that I referred to. When dragging a rotated element, I first unrotate it back to its original state. Otherwise, the drag operation on a rotated element takes the rotation into account, causing the drag direction to differ from the visible cursor movement.

Here are the rotation handlers:

  // rototion support

  var current_furniture = null;

  function rotate_item (item, angle) {
    if( null != item ) {
      item.rotate( angle );
      item.data( "angle",
        item.data( "angle" ) + angle );
    }
  }

  function rotate_current_cw () {
    rotate_item( current_furniture, 5 );
  }

  function rotate_current_ccw () {
    rotate_item( current_furniture, -5 );
  }

Here are the two text elements used to trigger rotation of the currently selected element:

  // rotate selected element

  var t2 = r
    .text(500, 380, "Rotate selected item")
    .attr({fill: "#fff", "font-size": 12})
    .click( rotate_current_cw );

  var t3 = r
    .text(580, 380, "ccw")
    .attr({fill: "#fff", "font-size": 12})
    .click( rotate_current_ccw );

I had a problem with the rotation on the iPad: apparently, on that platform, the drag-move-up handler overrides the click handler, which initially made it impossible to click any element to select it for rotation. The final solution I wound up with was adding functionality to the drag handler so that it handles the click event stuff as well.

Button

Finally, a rather trivial enhancement to clarify the usage of the text rotation elements. I simply added a rectangle around them to make it more obvious that they are actually buttons:

Button

Conclusion

So far I am happy with everything I have learned about both SVG and the Raphaël toolkit.

My original plan to implement a cloud-based round-trip 2D Revit model editing workflow on any mobile device using SVG still seems feasible.

One possible next step might be to implement a Revit add-in to export room boundaries and family instances representing furniture or other equipment. For the latter, a simplistic approach might export only the bounding box, or the largest area horizontal face, or, better still, the real outline looking from above. Another step would be implementing a cloud-based repository for this data. It can be retrieved and displayed using SVG on the mobile device and edited as shown above. The editing can include updating the repository data. The original Revit model can be updated on an explicit command call, or automatically, e.g. using the Idling event, e.g. via a WCF service.

URL and Other Buttons, XYZ Points and Vectors

Let me summarise a very few of the topics I have been chatting with people about in the past few days:

• Ribbon button identification
• Opening a URL from a ribbon button
• XYZ comparison and point and vector behaviour
• Autodesk API overview
• The Green Building Studio GBS REST API

Actually, to tell the truth, it is just one day, so far, this week. Wow, my days are too full. I am getting nothing else done!

Ribbon Button Identification

Here is a simple question that came up a few times in the past:

Question: I have implemented a ribbon push button. Now I would like to find out which button was pushed in the event handler, i.e. external command, so that I can attach the same external command to handle multiple different buttons. How can this be achieved, please?

I would like to identify the button pushed and access its data in the external command Execute method.

Answer: The official Revit API user interface design expects you to implement a separate command class for each push button.

If you do so, then you can identify the push button clicked by the user by the command class whose Execute method was triggered.

If you choose to circumvent this official approach somehow, e.g. by attaching the same external command implementation to several different push buttons, than you will have to identify them by some other means.

When you define a push button, you also specify its Name via the RibbonItemData.Name property. This name is unique across the entire ribbon, or at least within the panel containing the button, so you could use this to identify the button.

Unfortunately, the Revit API does not provide any support for finding out which push button was used to trigger the external command.

While this functionality is not provided by the Revit API, you may be able to make use of the generic .NET Framework libraries to find out.

For instance, you can subscribe to certain events to receive a notification whenever a ribbon button is pressed by making use of the .NET UI Automation library.

A concrete example of subscribing to a UI Automation event telling you which button was clicked is given by Rudolf Honke to pimp my ribbon, where he shows how to implement an event listener for both Revit and AutoCAD ribbon systems:

ComponentManager.UIElementActivated
  += new EventHandler<Autodesk.Windows
    .UIElementActivatedEventArgs>(
      ComponentManager_UIElementActivated );
 
void ComponentManager_UIElementActivated(
  object sender,
  Autodesk.Windows.UIElementActivatedEventArgs e )
{
  // e.UiElement.PersistId says which item has been pressed
}

You will need to test whether this is of any use to you. This event listener may be pretty inefficient and slow.

The use of these APIs is unsupported and at your own risk. If you wish to use the unsupported UI Automation option, you will have to find out for yourself how to do so using the ample information available on the web and elsewhere.

Probably the easiest way to go is indeed to implement a separate command handler for each button. If you have many commands requiring similar functionality, e.g. an identical initialisation procedure, you can either derive them all from one common base class, or wrap the common functionality in a method that you can call from each separate external command Execute method.

Opening a URL from a Ribbon Button

Another, simpler, question on hooking up ribbon buttons was also happily and rapidly resolved:

Question: I am attempting to create a URL link like this:

How can I enable the user to click on the button and get the link to open in a web browser? I know how to create the ribbon panel and push button, but not how to connect to the URL in a web browser.

Answer: Two options:

1. Official, easy, supported: implement an external command and launch the browser from that.
2. Unofficial, harder, unsupported: use something else, e.g. the .NET framework UI Automation library discussed above.

Response: Option #1 worked and it was very easy indeed. All it required was adding just one line of code in the external command, System.Diagnostics.Process.Start, and then simply implementing it in the external application file.

This enables us to populate a custom ribbon panel that includes URLs linking to PDFs and webpages containing office Revit standards. This provides our staff a quick and easy way to access our standards within the Revit environment.

External command:

External application:

Revit ribbon:

XYZ Comparison and Point and Vector Behaviour

A completely different topic deals with the Revit API XYZ class, its dual use to represent points and vectors, and how to compare them, raised by Graham Cook in the Revit API discussion forum in the thread on a XYZ.IsAlmostEqualTo problem:

Question: Maybe I'm misinterpreting the IsAlmostEqualTo method. I want to determine whether two points are within 4 inches of each other, i.e. 0.3333 feet. I thought the following code would achieve that:

  XYZ a = new XYZ(41.7, -76, 0);
  XYZ b = new XYZ(4.7, -76, 0);
  bool almostEqual = a.IsAlmostEqualTo(b, 0.333);

But even though in this example the two points are 37 feet apart, IsAlmostEqualTo returns true. Am I misunderstanding the tolerance part of the method?

Answer: The behaviour you observe is correct and intended and has a simple explanation:

IsAlmostEqualTo is implemented for vector comparison, not point comparison, and is mostly designed around small tolerances. The default for IsAlmostEqualTo with no tolerance input argument given is 1e-09. At small tolerances, points and vectors are more interchangeable, so I would use the default IsAlmostEqualTo to find "equivalent" points too.

Because this is a directional comparison, not a distance one, 0.333 for the epsilon means to check if the two vectors are within a significant angular range of each other, which the example input points actually pass. Even if the points are treated as vectors and normalized, they will still pass the comparison because of the wide epsilon permitted.

If you want to compare points with a non-tiny epsilon using the allowed distance between them, use XYZ.DistanceTo method instead.

The Util.cs module of The Building Coder samples provides example implementations of point comparison predicate methods. Here is version 2013.0.99.4 from the slab boundary command update.

Autodesk API Overview

Autodesk provides a large number of programming platforms and APIs. An overview is given by the Platform Technologies overview on the Autodesk Developer Network. Just to see and be astounded by their sheer number, here is a list of links to the associated developer pages:

• 3DS Max
• AutoCAD Architecture
• Autodesk Exchange Apps Developer Center
• AutoCAD
• AutoCAD Civil 3D
• Cloud & Mobile
• DWF
• FBX
• Inventor
• AutoCAD Map 3D
• Autodesk Infrastructure Map Server AIMS
• Maya
• MotionBuilder
• Navisworks
• Revit
• Vault
• Wiretap
• ObjectARX
• AutoCAD OEM
• RealDWG

The Green Building Studio GBS REST API

I recently played around with the BIM 360 Glue REST API and showed how to use Python to access it interactively. I also recently mentioned the new building performance analysis blog which discusses topics such as the Project Falcon computational fluid dynamics Revit add-in and GBS, the Autodesk Green Building Studio cloud-based energy analysis web service.

Emile Kfouri now pointed out this discussion of the GBS REST API that will certainly enable you (yes, you!) to achieve very cool things. I am looking forward to hearing about your ideas!

ToElementIds Performance

Conversion of a filtered element collector to an explicit .NET collection of elements or element ids is always costly and mostly avoidable and unnecessary.

Before getting to the details of that issue, here is another quick snapshot from our travels to the West European developer conferences. As you either know or might guess, one of the main topics of these is cloud and mobile development, e.g. looking at topics such as the BIM 360 Glue REST API and SDK and my hands-on exploration of how to access and use it via Python.

Funnily enough, the lighting in the Paris Charles de Gaulle airport is designed along a cloud scheme, so here is very low quality picture of us almost touching the clouds at the airport gate preparing to board the flight to Milano:

Ora siamo arrivati in Milano per un'altra conferenza di sviluppatori.

Returning to the Revit API, I recently mentioned a couple of FindElement and collector optimisations.

One of them is the fact that the conversion from a filtered element collector to a .NET collection is costly and should be avoided if possible.

Here is another observation related to that, brought up by Guy Robinson and answered by Scott Conover of the Revit API development team:

Question: I sometimes use the ToElementIds method, e.g. like this:

  var fc = new FilteredElementCollector( doc )
    .OfSomething()
    .ToElementIds();
 
  foreach( var elemId in fc )
  {
    var element = doc.GetElement( elemId );
  }

I noticed that this is about 25% slower than accessing the elements directly as follows:

  var fc = new FilteredElementCollector( doc )
    .OfSomething();
 
  foreach (var elem in fc)
  {
      var element = elem;
  }

I am wondering why the ToElementIds approach is so much slower?

Shouldn't the two approaches be equivalent?

Is there any good reason to use ToElementIds at all?

Not surprisingly, this ~25% slower figure has been the same on my tests ever since I started comparing in Revit 2012.

Answer: This is not unexpected.

ToElementIds and ToElements allocate a new concrete .NET collection containing the elements passing the filter. Then it returns this allocated collection to you, which involves a conversion from a native level collection to a managed object. This will take extra time as compared to a direct iteration.

Why might you use the ToElementIds variants? Well, you might need a concrete collection to store in memory. Or you might need a collection to pass as input to an API method like Delete – which you should definitely not call from the middle of a foreach iteration unless you like unexpected behaviour. This provides a shortcut to building this allocation.

For any sort of operation of the type "I want to read properties of each passing element" you can skip ToElements and the extra collection allocation.

Thank you Scott for these insights!

For one example of how this can be achieved, look at the aforementioned FindElement and collector optimisations. There are lots of other examples in many of The Building Coder discussions, since I consciously and consistently avoid this conversion whenever possible, i.e. almost always.

BIM 360 Glue REST API Authentication Using Python

I provided an overview of the BIM 360 Glue REST API and SDK last Friday and hinted at upcoming further exploration. Well, here it is already.

Due to Autodesk University and the world-wide developer conferences, I had to skip my last education day, but this stuff was too exciting to wait any longer :-)

So, unwilling to go for any length of time without trying out something new, I played a bit with the Glue API anyway.

For fun, I will describe here stepping through the exploration of the Glue authentication process completely manually, making use of the Python programming language and a handy library which probably provides an easier access to the REST API than you imagined possible. Here are the steps:

1. Python and requests
2. Get the Google page
3. Access BIM 360 Glue
4. Adding authentication
5. Timestamp and MD5 digest
6. More login credentials
7. Successful authentication

Python and Requests

Looking for an easy way to manually interact with REST, I immediately turned to Python and found the requests library, which describes itself as an 'awesome Python HTTP library that's actually usable'. I would agree that is a fair assessment.

Get the Google Page

Here is an example showing how simple it is to issue an HTTP request from scratch, including launching the Python interpreter from the command line; basically, it uses one single line of code, calling the method requests.get with the desired URL:

$ python
Python 2.7.2 (default, Jun 20 2012, 16:23:33)
[GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests
>>> r = requests.get('http://google.com')
>>> print r
<Response [200=""]>
>>> r.headers['content-type']
'text/html; charset=ISO-8859-1'
>>> r.content
'<!doctype html>
<html itemscope="itemscope" itemtype="http://schema.org/WebPage">
<head>
<meta content="Search the world\'s information, including webpages, images, videos and more. Google has many special features..."

The REST response 200 is a typical HTTP status code and means OK.

Accessing BIM 360 Glue

Ok, so requesting the Google home page is simple. Let's try accessing BIM 360 in a similar manner.

Trying to access something, e.g. query the model services, immediately reacts:

>>> u1='https://bim360.autodesk.com/api/model/v1/info.json'
>>> r = requests.get(u1)
>>> print r
<Response [400=""]>

Oops. Response codes in the 400 range indicate client errors. 400 itself stands for bad request.

Yes, of course, we need some authentication!

Time to start looking at the documentation. First, find out where it can be found at all. The starting point bim360.autodesk.com/api redirects us to bim360.autodesk.com/api/doc/index.shtml, providing human readable documentation and a link to the web services API documentation.

Adding Authentication

So, let's authenticate ourselves:

Looking at the Glue web services API documentation on creating a signed request, this requires some interesting bits and pieces besides the basic information, which consists of

• Company id
• API key
• API secret

The API key and secret need to be requested from Autodesk. Currently, there is no official developer program running for Glue. You can however buy a normal user account and ask for additional developer access based on that.

As we can see from the documentation, in addition to the API key and secret, plus the normal user account login credentials, the authentication requires a timestamp, more precisely a Unix epoch timestamp using GMT time, the number of seconds since the Unix epoch, January 1 1970 00:00:00 GMT.

The API key and secret are concatenated with the timestamp and encoded using an MD5 cryptographic hash to create a signature, which also has to be sent with the request.

Timestamp and MD5 Digest

Luckily, Python can easily support us in providing the timestamp and signature components.

The timestamp can be generated like this using the time module:

import time
def expires():
  '''return a UNIX style timestamp representing 5 minutes from now'''
  return int(time.time()+300)

The Python Standard Library Cryptographic Services includes the MD5 message digest algorithm 'md5', so that is also easily taken care of.

Following the example given in the Glue API documentation, I created the concatenation and digest of the following items:

• API Key: ddbf3f51b3824ecbb824ae4e65d31be4
• API Secret: 12345678901234567890123456789012
• UNIX Timestamp: 1305568169 - (5/16/2011 5:50:36 PM)

Here is the code doing that by hand, interacting with the interpreted environment:

>>> key='ddbf3f51b3824ecbb824ae4e65d31be4'
>>> secret='12345678901234567890123456789012'
>>> timestamp='1305568169'
>>> s=key+secret+timestamp
>>> s
'ddbf3f51b3824ecbb824ae4e65d31be4123456789012345678901234567890121305568169'
>>> import md5
>>> signature=md5.new(s)
>>> print signature
<md5 HASH="" object="" @="" 0x10c0b5d30="">
>>> print signature.hexdigest()
b3298cf0b4dc88450d00773b4449ba51

The hexadecimal digest exactly matches the signature string listed in the Glue documentation example, so we seem to be on the right track so far.

More Login Credentials

Studying the documentation further, we end up at the nitty-gritty internals of the Security Service: Login request, specifying the following full list of required parameters:

• format
• login_name
• password
• company_id
• api_key
• api_secret
• timestamp
• sig

Actually, I intuitively fixed an error or two when transferring this list; e.g. the secret was not mentioned at this point, and the timestamp has a wrong description associated with it. So do what every programmer always has to do: ignore the documentation (but only some of it!), trust your own insight, take everything with a grain of salt, and use your brains, intuition and good taste.

By the way, the user name and password required here are the Autodesk id single sign-on credentials, also known as SSO, formerly Autodesk unique login or AUL.

I initially tried to use a GET request and was kindly informed by a suitable error message that I should be using POST instead.

Successful Authentication

I ran into a couple of other not unexpected issues as well, and finally ended up with this method to construct the authentication POST request:

url = 'https://bim360.autodesk.com:443/api/security/v1/login.json'

def bim_360_glue_authenticate( login_name, password, company_id, api_key, api_secret ):
  timestamp = str(int(time.time()))
  sig=md5.new(api_key + api_secret + timestamp).hexdigest()
  data={
    'login_name' : login_name,
    'password' : password,
    'company_id' : company_id,
    'api_key' : api_key,
    'api_secret' : api_secret,
    'timestamp' : timestamp,
    'sig' : sig
  }
  r = requests.post(url, data=data)
  print r.status_code
  print r.headers['content-type']
  print r.content

This call succeeds and prints:

>>> bim_360_glue_authenticate( ... )
200
application/json; charset=UTF-8;
{"auth_token":"b61d3ec10a7042cf884806e4e5a55601","user_id":"b2409a28-08b4-4bd4-a935-a6e33d5b030d"}

Again, 200 means OK, i.e. success. Hooray!

Cool, huh?

There may be easier ways to achieve this, but hardly more instructive :-)

And as you can see, the interactive Python environment and rich library support really help a lot!

The resulting code is also pretty succinct, considering we are starting from absolute zero here.

How long would you have needed to explore and implement this in a compiled environment?

The BIM 360 Glue Viewer and REST API

As you certainly know by now, Autodesk provides a range of powerful cloud-based solutions, specifically Autodesk 360, PLM 360 and BIM 360 Glue (reference).

Of special interest to AEC developers, the BIM 360 Glue platform includes support for programming interfaces and a software development kit, the BIM 360 Glue SDK, providing a set of tools for developers to interface with it.

The programming support consists of two distinct components:

1. Display component: embeddable 3D viewer to provide visual access to models within custom third party web applications.
2. Web services API: REST based service data access to users, projects, models, etc.

Display Component

The Glue Viewer is an embeddable component used to show 3D models from the Glue platform

Viewer parameters allow control of the GUI, i.e. application controls such as navigation, display lists, etc., so the viewer experience can be customised by developers.

The viewer currently supports Windows 32 and 64 bit platforms, just like the Glue web application.

Web Services API

The Glue web services API provides a RESTful data access interface to query and modify data and return JSON or XML.

It enables developers to integrate external applications, e.g., project management systems, accounting systems and custom developed solutions with the BIM 360 Glue platform.

Glue stores information about user interactions within the system. These operations are referred to as 'Actions'. Typical Actions can be:

• Uploading a model
• Creating a view
• Adding mark-ups
• Creating a clash report

The Glue Web Service API returns many of these actions in API responses.

Actions can be loaded to the viewer to show the user the exact view and state of a model when the action was performed.

Structure of a Client Request

For a typical REST API request, the client sends a HTTP/HTTPS request, POST or GET, depending on the particular service call. Required parameters are sent to the server for authentication. An example URL for a login request could be something like:

https://bim360.autodesk.com/api/security/v1/login.json

The server responds with an HTTP Status of 200 for success and appropriate other codes for failures.

The Glue web service API provides the following service groups:

• Security Service: Responsible for security management of Glue user accounts.
• Project Service: Manage projects within the Glue platform.
• Model Service: Manage 3D models within the Glue platform.
• User Service: Manage user information.
• Action Service: Access and manage action records.
• System Service: Retrieve information and check availability.

Here is an example of a web services API call to the Model Service to retrieve information of a given model specified by the model_id:

https://bim360.autodesk.com/api/model/v1/info.json?
  &company_id=autodesk_jt
  &api_key=c7e595c69a35422c8414e51736f67761
  &auth_token=f79462fc5a5346ba9dbd4f395781f9b4
  &timestamp=1349801232
  &sig=de4c1771541d4789a1e63762c60b34f1
  &model_id=53c41451-49e7-4b0a-919c-1499604d10c6
  &sterm=
  &pretty=1

So what can we do with this?

With the SDK, partners and customers can build a variety of fully interactive web based custom applications and integrations taking advantage of the Glue platform.

A simple call flow for a custom application might be:

• Perform user authentication.
• Query and list available models.
• Use the Glue viewer to display the model within the custom application.

This enables tasks like system integration, project management, accounting, etc. The web services API provides full data access to system objects:

• Users
• Projects
• Models
• Actions

An application can automatically update projects, models, etc. with information from external systems.

Basically, we are looking at the following architectural hierarchy, from bottom to top:

• BIM 360 Glue Platform @ Amazon
• Internet Connectivity
• BIM 360 Glue API Server
• BIM 360 Glue API
• System Integrations Enabled via Glue API

Where do I start?

Download the BIM 360 Glue SDK,

You will need an API Key and an API Secret. These are unique identifiers assigned for each user, company, or partner.

Furthermore, a Glue developer account is required, a user name and password. A normal user account can be converted to a developer one on request.

There are even further levels: a default developer account works within the privileges of normal glue user, whereas a privileged developer account can perform requests on behalf of other users as well.

The authentication to the BIM 360 Glue Platform starts with an API key and secret assigned by Autodesk. Once you have these two pieces of information, API calls can be authenticated to the BIM 360 Glue Platform in one of two ways:

• User name and password; using the API key and secret, a signed request including the user name and password is sent to the BIM 360 Glue Service, which returns an authorisation token.
• The authorisation token is used for all subsequent calls.

Here is a quick reference to further sources of information and two examples:

• SDK overview
• Detailed web service API documentation
• Viewer support – file formats
• Integration with project management system – CMIC
• Glue embedded within a web application – Maximo

I am looking forward to hearing what you come up with using this, and to exploring it in more depth myself anon. Have fun!

AU Classes on Python, UI, Server and Framework APIs

Thursday was another very full and fruitful day at AU. I gave my third and last class, the most exciting one in my eyes, on some UI and integration aspects. I was unable to attend Iffat May's class introducing Python and using it in Revit and Vasari via RevitPythonShell, but I love her material so much I am including it anyway. Adam Nagy presented a class addressing cloud and mobile development and the Revit Server API. Finally, Arnošt Löbel provided a peek behind the scenes and into the depths of the fundamental frameworks underlying the Revit API.

Here they are in chronological order:

1. CP3837-L Scripting with RevitPythonShell in Vasari by Iffat May.
2. CP4107 Let's Face It: New Revit 2013 User Interface API Functionality by Jeremy Tammik.
3. CP3093 My First Cloud/Mobile App with Revit Server by Adam Nagy.
4. CP3426 Core Frameworks in the Revit API by Arnošt Löbel.

I am including the class materials below, for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

1. CP3837-L RevitPythonShell in Vasari

Iffat provides an entire introductory tutorial to the Python programming language, and then shows how to apply it to solve a number of useful tasks in Revit and Vasari. She makes use of Daren Thomas' Revit Python shell, originally implemented for Revit 2010, then for Vasari, Revit 2012 and Vasari 2.1, and now available for Revit 2013.

RevitPythonShell introduces interactive scripting ability to Revit and Project Vasari. Designers now have the ability to interactively design and manipulate Revit elements using algorithms and computational logic. The class explores the Python structures, variables, data types, and flow control, and shows how to use them to create scripts to control Revit elements dynamically.

• Handout
• Presentation
• Sample code and models

2. CP4107 Revit 2013 User Interface API

This class takes a deeper look at the new user interface and add-in integration functionality provided by the Autodesk Revit 2013 API. It covers 2013 features including Options dialogue custom extensions using WPF components, subscription to Revit progress bar notifications, embedding and controlling a Revit view inside an add-in dialogue for preview purposes, the new drag and drop API, and the UIView. This class is complementary to and expands on CP3272, a Snapshot of the Revit UI API:

• Document management and View API
• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embedding and controlling a Revit view
• UIView and Windows coordinates
• Drag and drop

From my point of view, one of the most exciting new features provided by the Revit 2013 UI API is the possibility to correlate between Windows screen device coordinates and Revit model coordinates provided by the UIView class, which I used to examine and implement my own Revit tooltip, which also makes use of the new ReferenceIntersector class and Idling event. This has never previously been possible. Now you can do anything you like using the Windows API and connect that intelligently with the underlying Revit model.

• Handout
• Presentation
• Sample code

3. CP3093 Cloud/Mobile App with Revit Server

This class has two objectives: to introduce you to the Revit Server REST API and to introduce you to cloud and mobile programming.

Autodesk Revit Server is a server-based file storage system that we can use to store Revit files. It has a public API that uses simple HTTP known as REST (or Representational State Transfer). REST is a "style" for designing network applications, and it is used to communicate between the server and a client machine. REST is simple, yet powerful enough. You can use it from anywhere where HTTP programming is available: from a desktop, a mobile device or a server-side application. In this class, we discuss what REST is, using the context of Revit Server.

We then go one step further and show you how to create your own REST service in .NET. We implement it as a notification system in the cloud and demonstrate with an Apple iPad/iPhone application in Apple iOS. At the end of this class, you will be able to:

• Use HTTP requests to interact with a REST API
• Programmatically access and modify data available on Revit Server
• Create basic iOS applications in Xcode
• Create a basic REST service in .NET
• Use Apple Push Notification

Here is the detailed handout document:

• Handout

4. CP3426 Core Frameworks in the Revit API

A good understanding of core frameworks in the Revit API is a prerequisite for developing well behaved Revit add-ins. Among the most important ones, the following frameworks play key roles in most applications:

• External applications, commands, and events
• Transactions phases
• Regeneration and transaction modes
• Updaters and other call-backs
• Scoped objects and element validity

These concepts have been around for many releases, yet there are still facts about them that may not be completely understood. This class summarizes the necessary basics, and also sheds some light on the behaviour that is normally hidden 'under the hood'. Knowledge acquired during this class will help Revit developers to build more efficient, safer, and robust applications.

• Paper
• Presentation

By the time you read this, I will be sitting in the plane heading back to Europe.

Take care, and walk in beauty.

Room Polygon and Furniture Picker in SVG

I documented a number of personal and possibly naive ideas and experiments regarding mobile device room location as a result of my previous so-called education day four weeks back. Well, last Friday I had another one :-)

This time I took a deeper and hopefully very slightly wiser look at ideas for enabling the following kind of workflow:

• Extract relevant data from the BIM.
• Populate a cloud database to provide ubiquitous access to relevant data.
• Serve up relevant data in an easily consumable format, e.g. for mobile devices.
• Enable interaction with the data, e.g. query and update.

I spent some time thinking about how to implement a suitable viewer with support for picking.

My colleagues Philippe and Adam have developed and documented a powerful and impressive cloud and mobile based workflow including a 3D viewer implementation supporting object selection for a number of CAD authoring environments, obviously including AutoCAD, Inventor and Revit, posting data to the cloud, e.g. Azure, for consumption on various Android and iOS mobile devices, etc.

I would love to be able to achieve the same effect with significantly less effort. Lazy...

I already suggested that it might be possible to use scalable vector graphics SVG for this kind of thing last time I looked at the cloud and mobile topic.

I still think it really does provide everything I need, since its base functionality includes support for interactivity, linking and metadata, among many other things.

My goal here today is to prove that SVG is a good choice for providing, displaying, and interacting with 2D graphical data.

It is supported by all devices and requires only minimal JavaScript programming to achieve useful results, so an easily tested and extremely portable cross-platform solution seems very feasible.

Today my goal is to supply the proof of the pudding. Specifically, I wish to prove that I can use SVG to achieve the following:

• Display a room boundary and contained items as coloured polygons using SVG. The items may be furniture, or any kind of family instance, e.g. simply represented by their bounding boxes.
• Embed the SVG into a standard HTML page displayable on any browser, so that it can be viewed and manipulated on any mobile device.
• Identify and interact with the displayed objects, e.g. identify the room or furniture and display information about a selected item.

I'll discuss the following steps towards this goal:

1. Embed SVG in HTML
2. Colour picker
3. Polygons and groups
4. Room and furniture picker
5. Struggle with Safari

Embed SVG in HTML

I would very much like to show you the results of my SVG experiments right here and now on this page.

An easy way to almost achieve this would be to simply provide normal hypertext links to the different SVG web pages I describe.

A much nicer, more elegant and compelling approach is obviously to embed the SVG directly into this page, which presumably ultimately consists of HTML.

There are a number of different possibilities to embed SVG into HTML, which as always are somewhat browser dependent.

After some experimenting in the Typepad blog editor, I decided to use the embed tag, which is consequently the technique you will be enjoying further down if you read on.

All my following examples are accessible in two ways, both using a hypertext link to open up a new page presenting the SVG, and an embedded inline version that you can interact with in situ. You can of course view this page's source in your browser to examine both methods.

Colour Picker

I started out searching the web for the terms "svg pick".

One hit was a pretty impressive SVG colour picker implemented and published by Kevin Hughes in 2004 as a way to learn SVG:

It includes documentation, links to learn SVG, and additional SVG notes.

A colour picker seems like a good starting point, although I found this particular example a bit overwhelming for a project that I was hoping to finish in just a couple of hours. I searched for something simpler instead, and turned up a presentation on using canvas in SVG by Klaus Förster of the University of Innsbruck including a much simpler CSS3 colour picker which helped get me started implementing my very own colour picker:

Do as the man says: click on one of the little coloured rectangles at the top, and the selected colour is displayed in the bottom.

That provides pretty conclusive evidence that we really can display simple geometric shapes, interactively pick them, and react on the selection, all within a standard web page in a browser with no additional software installed, doesn't it?

How is this achieved?

This implementation requires three files: an image displaying the coloured boxes to select at the top, a JavaScript helper file, and the SVG itself.

The main component is the following SVG code, embedded into the HTML page using the embed tag (copy to a text editor to see the truncated lines in full):

<?xml version="1.0" encoding="us-ascii" ?>
<svg xmlns="http://www.w3.org/2000/svg" 
     xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Jeremy's SVG color picker</title>
<script type="text/javascript" xlink:href="SVGCanvasElement.js" />
<script type="text/javascript"><![CDATA[
window.onload = function() {
  var canvas = new SVGCanvasElement(10,10,240,240);
  var context = canvas.getContext('2d');
  var image = document.getElementById('svgImage');
  var hint = document.getElementById('svgHint').lastChild;
  var active = document.getElementById('activeColor');
  var marked = document.getElementById('markedColor');
 
  context.drawImage(
    canvas.importImage(image),0,0,canvas.width,canvas.height
  );
  context.canvas.parentNode.style.display = 'none';
 
  image.onclick = function(evt) {
    var sx = evt.clientX-image.x.baseVal.value;
    var sy = evt.clientY-image.y.baseVal.value;
    var pxArr = context.getImageData(sx,sy,1,1).data;
    var fill = 'rgb('+pxArr[0]+','+pxArr[1]+','+pxArr[2]+')';
    var opac = 1.0/255.0*pxArr[3];
    active.setAttributeNS(null,"fill",fill);
    active.setAttributeNS(null,"fill-opacity",opac);
    marked.x.baseVal.value = evt.clientX - (sx % 20);
    marked.y.baseVal.value = evt.clientY - (sy % 20);
    hint.firstChild.nodeValue = "fill='"+fill+"' fill-opacity='"+opac+"'";
  };
};
]]></script>
 
<image id="svgImage" x="10" y="10" width="240" height="240" xlink:href="img/svg_css3_colors.png" />
<rect id="activeColor" x="10" y="260" width="240" height="30" stroke="#000" fill="none" shape-rendering="crispEdges"/>
<rect id="markedColor" x="-20" y="-20" width="19" height="19" stroke="#000" fill="none" shape-rendering="crispEdges"/>
<text id="svgTipp" x="10" y="310" font-size="16px">click CSS3 color palette to pick a color</text>
<text id="svgHint" x="10" y="330" font-size="16px"><tspan></tspan><tspan>picked</tspan></text>
</svg>

I must admit that I did have to fiddle around considerably in the blog hosting file manager to figure out where best to place the three inter-dependant files. The best solution, as always, was the simplest.

This colour picker is completely based on Klaus' work, with only minimal cleanup and perfectionistic improvements, such as painting a 19 by 19 rectangle around the picked colour instead of a 20 by 20 one.

Again, how does it work? The SVG code defines five elements:

• The image element to display an image presenting all the selectable colours.
• A large rectangle at the bottom to be filled with the currently selected colour.
• A small 19 by 19 pixel rectangle to be moved around to mark the current colour selection inside the palette image.
• A static text element prompting you to pick a colour.
• A dynamic text element displaying the large rectangle's current fill and fill-opacity attribute values.

These elements are retrieved using a snippet of JavaScript code executed on loading the page. The code also subscribes to the JavaScript onclick event. The event handler manipulates the elements as shown. Specifically, the getImageData function retrieves the colour and opacity of the picked point, which is used to calculate the settings and populate the various elements appropriately.

I would say that this provides a credible proof of concept.

Polygon and Groups

Next step: as said, I want to display a room retrieved from the building model and various items contained in it using polygons.

How do I display an arbitrary polygon in SVG?

Searching the web turned up this succinct and complete polygon with a hole sample SVG file which basically says it all with no need for any further explanation at all:

It displays a quadrilateral polygon with a triangular hole, which requires just one single SVG element, and adds a group around it for identification purposes:

  <g id="polygon" transform="translate(0.5,50.5)">
    <path d="M 35 -10 L 10 -20 15 -40 45 -45 Z M 20 -30 L 35 -35 30 -20 Z" 
          style="fill:blue;fill-opacity:0.2;stroke:blue;stroke-width:1" 
          fill-rule="evenodd" />
  </g>

I must admit that I went no further to read any documentation; I just based all my further experiments on the following assumptions and guesswork. Will I regret this? It was quick and fun, anyway. And it worked :-)

Just guessing, I assume that 'M' stands for 'move to', and 'L' stands for 'draw a line to', and 'Z' closes the polygon. These keywords are followed by pairs of X and Y coordinates to define the polygon loop start and vertex points. Note the 'evenodd' fill-rule attribute, which I assume leaves holes in odd-levelled interior loops. I further assume that an interior loop within a hole is considered filled again with this setting. Cool.

As you can try out and see for yourself in the room picker provided below, the hole is indeed not considered to be part of the polygon, and picking inside the hole will return nil.

In addition to the polygon, which is what it is all about, this neat little example also adds X and Y gridlines to simplify orientation and analysis, plus square markers for the polygon vertices, filled for the start and empty for the subsequent points.

Here is the complete SVG file implementing all this. Note the three groups defined around the grid lines, polygon, and marker points:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created on 15 Mar 2011 by Mike Toews in Vim -->
<svg
  xmlns:svg="http://www.w3.org/2000/svg"
  xmlns="http://www.w3.org/2000/svg"
  version="1.1"
  width="51"
  height="51">
  <g id="background">
    <rect width="51" height="51" fill="white" />
  </g>
  <g id="grid" transform="translate(0.5,0.5)">
    <line x1="0" y1="0" x2="50" y2="0" style="stroke:#ddd;stroke-width:1"/>
    <line x1="0" y1="10" x2="50" y2="10" style="stroke:#ddd;stroke-width:1"/>
    <line x1="0" y1="20" x2="50" y2="20" style="stroke:#ddd;stroke-width:1"/>
    <line x1="0" y1="30" x2="50" y2="30" style="stroke:#ddd;stroke-width:1"/>
    <line x1="0" y1="40" x2="50" y2="40" style="stroke:#ddd;stroke-width:1"/>
    <line x1="0" y1="50" x2="50" y2="50" style="stroke:#ddd;stroke-width:1"/>
    <line x1="0" y1="0" x2="0" y2="50" style="stroke:#ddd;stroke-width:1"/>
    <line x1="10" y1="0" x2="10" y2="50" style="stroke:#ddd;stroke-width:1"/>
    <line x1="20" y1="0" x2="20" y2="50" style="stroke:#ddd;stroke-width:1"/>
    <line x1="30" y1="0" x2="30" y2="50" style="stroke:#ddd;stroke-width:1"/>
    <line x1="40" y1="0" x2="40" y2="50" style="stroke:#ddd;stroke-width:1"/>
    <line x1="50" y1="0" x2="50" y2="50" style="stroke:#ddd;stroke-width:1"/>
  </g>
  <g id="polygon" transform="translate(0.5,50.5)">
    <path d="M 35 -10 L 10 -20 15 -40 45 -45 Z M 20 -30 L 35 -35 30 -20 Z" 
          style="fill:blue;fill-opacity:0.2;stroke:blue;stroke-width:1" 
          fill-rule="evenodd" />
  </g>
  <g id="points" transform="translate(-1.5,48.5)">
    <rect id="outer point 1/5" width="4" height="4" 
          transform="translate(35,-10)" 
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="outer point 2" width="4" height="4" 
          transform="translate(10,-20)" 
          style="fill:white;stroke:blue;stroke-width:1" />
    <rect id="outer point 3" width="4" height="4" 
          transform="translate(15,-40)" 
          style="fill:white;stroke:blue;stroke-width:1" />
    <rect id="outer point 4" width="4" height="4" 
          transform="translate(45,-45)" 
          style="fill:white;stroke:blue;stroke-width:1" />
    <rect id="inner point 1/4" width="4" height="4" 
          transform="translate(20,-30)" 
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="inner point 2" width="4" height="4" 
          transform="translate(35,-35)" 
          style="fill:white;stroke:blue;stroke-width:1" />
    <rect id="inner point 3" width="4" height="4" 
          transform="translate(30,-20)" 
          style="fill:white;stroke:blue;stroke-width:1" />
  </g>
</svg>

Room and Furniture Picker

With all of this in hand, let's hand-craft a sample SVG file displaying a room and a couple of bits of furniture, allowing us to pick individual elements , reacting to and displaying the pick results.

After the preparation above, it is surprisingly easy, actually, and impressively self-contained. Here is Jeremy's room and furniture picker:

Here is the entire implementation, omitting most of the trivial grid line definition (copy and paste to an editor to see the full truncated lines):

<?xml version="1.0" encoding="us-ascii" ?>
<svg
  xmlns:svg="http://www.w3.org/2000/svg"
  xmlns="http://www.w3.org/2000/svg"
  version="1.1"
  width="241"
  height="201">
  <title>Jeremy's SVG Room and Furniture Picker</title>
  <script type="text/javascript">
    <![CDATA[
window.onload = function() {
  var result = document.getElementById('result');
  window.onclick = function(e) {
    var id = e.target.id;
    if(0==id.length){id="<nil>";}
    var x = e.clientX;
    var y = e.clientY;
    var s = "id='" + id + "' @ " + x + "," + y;
    result.firstChild.nodeValue = s;
  };
};
]]>
  </script>
 
  <g id="background">
    <rect width="300" height="200" fill="white" />
  </g>
  <g id="grid" transform="translate(0.5,0.5)">
    <line x1="0" y1="0" x2="240" y2="0" style="stroke:#ddd;stroke-width:1"/>

...

  </g>
  <g transform="translate(0.5,0.5)">
    <path id="room"
      d="M 20 20 L 220 20 220 150 150 150 150 100 20 100 Z M 160 120 L 210 120 210 140 160 140 Z"
      style="fill:blue;fill-opacity:0.2;stroke:blue;stroke-width:1"
      fill-rule="evenodd" />
  </g>
  <g id="furniture" transform="translate(0.5,0.5)">
    <rect id="table" width="100" height="20"
          transform="translate(50,50)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair1" width="8" height="10"
          transform="translate(37,55)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair2" width="10" height="8"
          transform="translate(60,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair3" width="10" height="8"
          transform="translate(80,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair4" width="10" height="8"
          transform="translate(100,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair5" width="10" height="8"
          transform="translate(120,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
  </g>
  <text id="result" x="20" y="180" font-size="16px">Welcome. Please click around.</text>
</svg>

Well, that was interesting for me at least.

A logical next step would be the implementation of a web service as described above to be populated with room and furniture data and serve it up on request in SVG and other formats.

No need for an own viewer implementation; I can use the functionality built into the browser on my mobile device.

Struggle with Safari

Oh no!

There I was, proudly bragging my head off about the cross-browser capabilities of SVG, and thinking I had solved all problems in the world.

I just tested my furniture picker on both an iOS iPad and an Android tablet.

Thank God it works on one of them.

Unfortunately the Safari browser does not react to the picks.

I may or may not have made some error in my SVG or JavaScript coding that Safari does not like and other browsers overlook.

It may or may not work with some other browser on iOS.

I may or may not find a solution that is better still.

Ouch, painful. Sorry. Still, there we are for the moment.

A happy update: I found a solution by Phil Archer of W3C of that does work on Safari as well as my PC Firefox and Android tablet browser, a simple SVG in HTML test page.

Phil says that the preferred method is to use the object element and define the SVG file using the src attribute.

He further presents samples using embed and iframe.

All three work fine on all browsers I tested, including Safari on the iPad.

I reimplemented my room and furniture picker JavaScript code based on Phil's sample SVG. Here is a normal hypertext link to the updated cross-country implementation, as well as inline versions using both embed and object tags. They all work on all browsers I tested, which include Firefox on the PC, Safari on the iPad, and the Android browser:

Hypertext link:

room_pick_3.svg

Embed:

Object:

For completness' sake, here is the updated source code:

<svg 
   xmlns='http://www.w3.org/2000/svg' 
   xmlns:xlink='http://www.w3.org/1999/xlink'
   onload='startup(evt)'>
 
<script><![CDATA[
  var SVGDocument = null;
  var SVGRoot = null;
  var count=0;
  var svgns = 'http://www.w3.org/2000/svg';
  var xlinkns = 'http://www.w3.org/1999/xlink';
  var result = null;
 
function startup(evt){
  O=evt.target
  SVGDoc = O.ownerDocument;
  SVGRoot = SVGDoc.documentElement;
  result = SVGDoc.getElementById('result');
  O.setAttribute("onclick","report(evt)");
}
function report(evt){
  id = evt.target.id;
  if(0==id.length){id="<nil>";}
  x=evt.clientX; 
  y=evt.clientY; 
  s = "id='" + id + "' @ " + x + "," + y;
  result.firstChild.nodeValue = s;
}
]]></script>
 
  <g id="background">
    <rect width="300" height="200" fill="white" />
  </g>
  <g id="grid" transform="translate(0.5,0.5)">
    <line x1="0" y1="0" x2="240" y2="0" style="stroke:#ddd;stroke-width:1"/>

...

    <line x1="240" y1="0" x2="240" y2="200" style="stroke:#ddd;stroke-width:1"/>
  </g>
  <g transform="translate(0.5,0.5)">
    <path id="room"
      d="M 20 20 L 220 20 220 150 150 150 150 100 20 100 Z M 160 120 L 210 120 210 140 160 140 Z"
      style="fill:blue;fill-opacity:0.2;stroke:blue;stroke-width:1"
      fill-rule="evenodd" />
  </g>
  <g id="furniture" transform="translate(0.5,0.5)">
    <rect id="table" width="100" height="20"
          transform="translate(50,50)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair1" width="8" height="10"
          transform="translate(37,55)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair2" width="10" height="8"
          transform="translate(60,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair3" width="10" height="8"
          transform="translate(80,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair4" width="10" height="8"
          transform="translate(100,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
    <rect id="chair5" width="10" height="8"
          transform="translate(120,75)"
          style="fill:blue;stroke:blue;stroke-width:1" />
  </g>
  <text id="result" x="20" y="180" font-size="16px">Welcome. Please click around.</text>
</svg>

Of course, if you are a real programmer, you will not trust me that the code presented above is up to date, follow the links above to the real live SVG file, and view its source instead.

Wow, that was quite a bit of extra unexpected effort. I'm afraid my education day stretched on a little bit beyond Friday... I hope you find it useful.

Immutable UV and XYZ Classes

Turning to a completely different topic:

The UV and XYZ classes were made immutable in Revit 2011, obviously also affecting other elements like the PointLoad Force and Moment properties.

I provided some explanations for this change back then in 2010, and would now like to add the point provided by Albert Szilvasy via Kean Walmsley to explain why AutoCAD.NET Point2d and Point3d objects are immutable:

The same reason why System.String is immutable.

The problem is that a mutable type is confusing to use when it appears as a property return value. For example:

  class A
  {
    public XYZ prop {get;}
  };

  A a;

  a.prop.X = 1.0;

Would this syntax mean that I can set the X value of a read-only property? Or would this simply mean that I set the X value of a temporary point object returned by prop?

Just as Kean says: there you have it. :-)

Unfortunately, there are some other areas in the Revit API where this very confusion still arises from time to time.

Point Cloud Request Batching

Here is some important information for point cloud engine developers, who may be confused by the SDK samples provided.

Question: We have taken the Revit point cloud engine example provided and modified it to create three cells, each loading its points from an ASCII file. The cell boundary is then drawn as blue random points.

We noticed that the maximum number of points ever requested is 512 * 512 and decreases as you zoom out. This number is applied to all cells, so the third and second cells disappear rather that fewer points being drawn in each cell.

This of course prompts some questions:

1. What sets the size of the buffer that is to be filled with points?
2. How does the point engine pass the buffer to each cell such that a closer cell would be requesting more points than one in the distance?

Answer: An instance of the IPointCloudAccess class will be requested by Revit when drawing the point cloud in the view. For performance reasons, when rendering every frame, Revit asks the engine to fetch the necessary points split into multiple batches. The number of batches requested depends on the view: the smaller the projection of the cloud bounding box on the screen the fewer batches Revit requests. Revit assumes that each batch contains points uniformly distributed over the visible part of the cloud ('visible' as defined by the filter). Thus, the points supplied by the engine should not be geometrically distinct, e.g. divided into multiple independent volumes, because otherwise, at distant zoom levels, Revit will only request a few batches and only part of the cloud will be displayed.

In other words, on every frame, Revit asks the engine to fetch some number of points in a few batches. Each batch is 256K points. The number of batches requested depends on the frame: the smaller the projection of the cloud bounding box on the screen, e.g. when you zoom out or orbit, the fewer batches Revit requests. Revit assumes that each batch contains points uniformly distributed over the visible part of the cloud, where 'visible' is defined by the filter.

In the sample code, the plug-in does the complete opposite: it groups points in a few cubes, 256K each, and returns one cube per requested batch. So if Revit requests 3*256K points, it gets three cubes, but if you zoom out and Revit requests only 2*256K points, it receives only 2 cubes. In this example Revit expects to get 2*256K points uniformly distributed over the 3 cubes.

This assumption is currently not reflected adequately in the documentation. Sorry! It should say something like:

The main purpose of the engine is to quickly fetch points from one point cloud file satisfying certain conditions described in the client query. Typical request would be to get specified number of representative points within specified volume, e.g. a view frustum. By representative we mean that it is responsibility of the engine to make sure that the points being returned give a good idea of the distribution of all points satisfying the query rather than, e.g. concentrating all in one area.

This simply shows how a contrived SDK engine sample may not provide the best example for real-world usage, not having a database of points which can be queried representatively.

Programmatically Flip Work Plane

Saikat Bhattacharya provided a very clear and succinct explanation on flipping the the work plane for a family instance, and a code sample using the IsWorkPlaneFlipped property to achieve this programmatically.

IFC Export Area Calculation and Other Enhancements

Here is a typical question that may arise when working with IFC export and shows the importance of the extension possibilities provided by the IFC export open source project:

Question: How are the areas and volumes of walls, rooms, floors, etc. calculated for the IFC export? Are any standards being used?

Some examples of values and parameters in question when we export IFC files from Revit:

• For rooms IfcSpace under BaseQuantities: GrossFloorArea, NetFloorArea; these values are the same in my trials.
• Base quantities of walls are missing for IfcWall but present in IfcWallStandardCase; why is this?
• For IfcWall under dimensions (IfcPropertySet): Area, Volume, Length.
• For IfcWallStandardCase under BaseQuantities (IfcElementQuantity): Height, Length, Width, GrossSideArea, GrossFootPrintArea, GrossVolume.

Some other CAD products define other parameters as well; for example, a wall may provide both GrossSideArea and NetSideArea, GrossVolume and NetVolume.

Can we get this from Revit also? Would this require us to modify the export, e.g. through the open source project, calculate net parameters, and so on?

Answer: Good questions!

• Regarding the rooms IfcSpace BaseQuantities GrossFloorArea and NetFloorArea: I think currently they point to the same internal area, which of course is not ideal. Revit only has one type of room area calculation at a time, so it is a bit difficult to get multiple areas from the same room.
• Some of the wall areas are calculated based on the extrusion that is generated on output. Generally, for IfcWall, there is no extrusion, so we can't calculate the particular values. That said, we can re-examine to see if there are more properties that can be retrieved directly from the original Revit element.
• Regarding 'more parameters from other products': I'll summarize how it currently works, and what could be done:
  1. We generally export the parameters that Revit already calculates. The IFC export intentionally does not implement a lot of its own 'QTO' (Quantity Take-Off) calculations.
  2. Since the IFC code was originally written for QTO, it is possible that more Revit quantities have been added to the project since then. Adding to the open source project would easily write out those quantities to the IFC file.
  3. For others, we would have to do some calculations. These could be done as part of the open source project, requested from the Revit development team, or implemented as a separate Revit add-in, e.g. by adding custom parameters or extensible storage data to the model, which the IFC export could pick up and handle if it is found.

If you are thinking of amending the open source code and you make changes that you think would be beneficial to the entire community, we'd appreciate if you considered 'donating' your changes to the project.

Async and Await Easily Enable Asynchronous Interaction

Continuing our cloud and web service ruminations, here is an interesting little hint on asynchronous interactions:

If you are thinking of implementing asynchronous interaction in your web service, which is often a very commendable and necessary thing to do in order to ensure responsiveness and avoid user frustration at a program that just hangs and does nothing, you can save yourself a lot of effort by looking at the async and await keywords provided in the .NET Framework 4.5 Beta.

The asynchronous programming model used in last few years requires a lot of careful attention while coding, which is tremendously simplified by the async features in the latest versions of C# and Visual Basic.

For a very readable overview of this new feature, here is an MSDN article by Brandon Bray, Async in 4.5: Worth the Await, and an async and await FAQ by Stephen Toub.

Unfortunately, as far as I can tell, .NET 4.5 cannot be used with Visual Studio 2010, so I cannot play with this until I move on a bit, which I will try to postpone until I get a new machine, which should happen any time now. I recently installed MVC 4 and thus proved first-hand that it works with VS 2010, which in turn proves that that does not require .NET 4.5.

Mobile Device Room Location

I had a so-called education day last Friday, and one of our current goals for these days is to learn about mobile and cloud computing. Here is my account of activities and research that day. Please excuse me for exposing my fallibility in this rambling account of a spontaneous unstructured single-person work-in-progress project.

The task I set myself was to query the location of a mobile device and determine the room it is located in in the Revit model.

That led to a number of interesting issues and explorations, some of which I was able to complete right away, and others to leave for another day:

1. Scenario.
2. Architectural considerations.
3. Mobile indoor positioning.
4. Coordinate system and multi-user considerations.
5. Android location and altitude.
6. Scalable Vector Graphics SVG.
7. Azure web service.
8. Installing the Windows Azure SDK.
9. Installing ASP.NET MVC 4.
10. Implementing an ASP.NET web service.
11. Enabling a non-numerical id in the URL.
12. Thoughts on the web service grammar.
13. Adding a levels controller.
14. Summary and next steps.

I did think of breaking this up into several posts, and cleaning up some of the results a bit more before publishing, then decided to leave it as is.

Please be aware that this is work in progress, or even less, notes on research and general head-scratching in progress. It would be useful to discuss my ideas and results with peers before writing about them, but I am here all by my little lonesome and will simply share them with you instead. These notes will be useful for me personally for future reference and may or may not be of interest to others.

Especially the ASP.NET results are still pretty wobbly :-)

1. Scenario

Imagine the following scenario:

I am running around inside a building with a mobile device, taking notes of things. As I take notes, I wish the device to automatically determine which room or space it is located in. Does that make sense?

I thought of various approaches to implement this kind of room determination.

I am assuming we have a Revit model specifying the rooms and their geometry. The room geometry could be handled as 3D volumes, or we could work with 2D boundary polygons in conjunction with the level information.

We are dealing with at least two and possibly three active agents: the Revit session on a PC somewhere, the mobile device, and potentially a web service on the cloud, accessible to both.

I am looking at the interaction between two or three agents here: the Revit session with the BIM, presumably running some custom add-ins, the mobile device and its location sensor, and optionally a web service on the cloud. I'll call them 'Revit', 'mobile device' and 'web service' henceforth.

I have several choices to make, such as which of the three agents to set up to perform the actual calculation? There are various pros and cons here:

• Calculate in Revit? That would be really easy, once we have the GPS data converted to the local model coordinates, because we can simply call the GetRoomAtPoint method. The hard part is to have Revit running as a ubiquitously accessible web service. There is a license issue, and even if we implemented it, we would still have to put the calculation into something that can be driven from outside, like an Idling event handler.
• Calculate on the mobile device? That would require many copies of the data on each device.
• Calculate in a web service?

Actually, the latter looks like the cleanest choice.

2. Architectural Considerations

Let's revisit the issue from a slightly different perspective.

Here are another couple of sketches of scenarios for locating the room in a building from the mobile device location:

1. Obtain the 3D location from the mobile device and pass it to a web service which communicates real-time with a running Revit session. In the Revit session, open the appropriate document, if needed, translate the mobile device location information to a model space XYZ point, and call the Document.GetRoomAtPoint method to determine the room.
2. Ask the mobile device user to specify what building level she is working on. Use that to enhance the 3D location from the mobile device and pass it to a web service which communicates real-time with a running Revit session. In the Revit session, open the appropriate document, if needed, translate the mobile device location information to a model space XYZ point, and call the Document.GetRoomAtPoint method to determine the room.
3. Export the Revit model room 3D volumes to the cloud. On the mobile device, use the location, optionally enhanced with user-defined level data, and find the volume containing that point.
4. Export the Revit model room 2D polygons to the cloud in separate levels. On the mobile device, use the location to determine the 2D location, and ask the user to specify the level, then find the polygon on the appropriate level containing the given 2D point.

My current tendency is to simply export the room boundary polygons per level.

Other considerations include:

• Use 3D volume or 2D polygon plus level information?
• Prompt user to manually enter current level? Yes, I think so.
• Data format? Simple list of closed polygon points passed to the web service?
• Data visualisation? Yes, we could easily implement a nice visualiser, e.g. using SVG. The web service could hold a database of polygon point data and render it to SVG on request.

At the moment, I am thinking of a room collector web service offering the following functionality:

• Add room: caller supplies room name, level, room boundary point data. Check for uniqueness, calculate bounding box and add to database, e.g. to dictionary within level dictionary.
• Retrieve room: caller supplies level and mobile device location point data. Retrieve the containing room via level, bounding box analysis to speed up the search, and finally a point in polygon algorithm.
• List levels: return all level names, so that they can be listed and selected on the mobile device.

Obviously this does not cover all the required functionality, so much more is still to be defined.

Anyway, it seems pretty straightforward to me to implement a mobile device room determination service using the following architecture and workflow:

• Implement a Revit add-in to export all the room polygons to the web service, separated by level.
• Store the room polygon database on the cloud, e.g. using Windows Azure.
• Optionally automate the storage, so that every document save updates the cloud database, as described by Saikat.
• Implement a web service query taking an input 3D point, optionally with a level attached, and determines the room polygon containing that point.
• On the mobile device, determine the 3D location, possibly asking the user to manually define which level she is working on.
• Query the web service for the room containing the current location point.
• Implement room polygon visualisation: query the web service for a room or all rooms on an entire level to be rendered to SVG.

3. Mobile Indoor Positioning

The In-Location Accurate Mobile Indoor Positioning Industry Alliance was announced last month.

I guess I will go for this topic, even though it is hard to make real practical use of it immediately.

One basic question, before we even get started, is this:

Question: Does the mobile device location service work well enough at all to determine what room or space it is in within a building?

If so, does it always work that well, or only sometimes?

What can one do to improve precision if needed?

I asked Kean, and his reply is:

Answer: In my experience it’s not there yet. Current technologies are based on proximity to Wi-Fi access points. Best results are obtained when it’s possible to triangulate.

Currently, the best chance of solving this may be the recently founded In-Location accurate mobile indoor positioning industry alliance.

Anyway, for the sake of argument and experimenting, let's assume that this issue can be solved.

If so, how can we correlate the mobile device positioning with the Revit BIM room boundaries?

4. Coordinate System and Multi-user Considerations

One interesting open issue is what coordinate system to work in.

I'll use Android as the mobile device example here, leaving the iOS based ones to Adam et al.

The Android location service provides longitude and latitude via the GPS and Wi-Fi networks, so it makes sense to work in that. The altitude is apparently given in meters as explained below.

Assuming that no two rooms or spaces can be in the same physical location, and that all the data passed in is correctly defined and positioned, that allows me to simply ignore all multi-user considerations.

I might decide to allow rooms to be identified by their unique Revit id, so that they can be told apart, and their data corrected.

Oh yes, it would also make sense to implement functionality to clear the entire database, and to delete individual levels and rooms.

5. Android Location and Altitude

Retrieving a precise fix of the mobile device location is not trivial, as this discussion on the simplest and most robust way to get the user's current location in Android shows.

Obtaining the altitude is even more unreliable; in the words of Jonas in the question of how Android GPS Location getAltitude method works:

The altitude value you get is in meters from the GPS (WGS84) reference ellipsoid and not from the geoid. From my experience, the GPS are really bad at altitude values. Here is a quote from the GPS Status FAQ:

"GPS does not report the height above the mean sea level; rather the GPS system compares the height to the WGS84 reference ellipsoid which may be above or below the actual sea level. In different parts of the earth it can be off by more than 200 meters (depending on the mass distribution of Earth). For example the geoid's surface around Florida is above the mean sea level by a good 30-40 meters, which means that standing on the shore would show you -30m as altitude. This is normal, and not an error, and caused by the fact that the altitude is relative to an artificial reference surface and not to the sea level. If you are interested in this topic, I recommend reading Mean Sea Level, GPS, and the Geoid."

In summary, the mobile device altitude reading might be too unreliable for locating rooms on different levels.

For an introduction to determining an Android mobile device location, here is a complete little tutorial describing the TrivialGPS application which will display a MapView and centre it on the current device location in real-time as it moves around.

For a complete video tutorial introduction to Android development and a huge number of other programming and non-programming topics, you can look at the New Boston, with 200 videos on Android development and 37 on iPhone development. I had a quick look at its Android application development tutorial 142 on the LocationManager and location permissions.

6. Scalable Vector Graphics SVG

Thinking about the room polygons, I also wondered about visualising them.

One handy way to achieve that is to use the Scalable Vector Graphics format SVG.

It is a W3C open standard XML-based file format for two-dimensional vector graphics enabling a pretty compact representation of polygons, and can be visualised on just about any browser, including mobile devices.

By the way, reading the details of the SVG polygon specification, I really love the precision of the specification of its list of points, the grammar for points specifications:

The following is the Extended Backus-Naur Form (EBNF) for points specifications in 'polyline' and 'polygon' elements. The following notation is used:

    *: 0 or more
    +: 1 or more
    ?: 0 or 1
    (): grouping
    |: separates alternatives
    double quotes surround literals

list-of-points:
    wsp* coordinate-pairs? wsp*
coordinate-pairs:
    coordinate-pair
    | coordinate-pair comma-wsp coordinate-pairs
coordinate-pair:
    coordinate comma-wsp coordinate
    | coordinate negative-coordinate
coordinate:
    number
number:
    sign? integer-constant
    | sign? floating-point-constant
negative-coordinate:
    "-" integer-constant
    | "-" floating-point-constant
comma-wsp:
    (wsp+ comma? wsp*) | (comma wsp*)
comma:
    ","
integer-constant:
    digit-sequence
floating-point-constant:
    fractional-constant exponent?
    | digit-sequence exponent
fractional-constant:
    digit-sequence? "." digit-sequence
    | digit-sequence "."
exponent:
    ( "e" | "E" ) sign? digit-sequence
sign:
    "+" | "-"
digit-sequence:
    digit
    | digit digit-sequence
digit:
    "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
wsp:
    (#x20 | #x9 | #xD | #xA)+

Cool, isn't it? Leaves no open questions!

I'll leave SVG be for now, and probably return to it later on. The visualisation is not an essential part of the room determination, of course.

7. Azure Web Service

I installed the Windows Azure SDK for .NET to use with my Visual Studio 2010 SP1 installation.

I also found it handy to take a look at Saikat's experiences with this as well.

8. Installing the Windows Azure SDK

I followed Kean's suggestions for exposing a web service using ASP.NET and first used the Visual Studio new project wizard to enable the Windows Azure tools:

That initialises a download process:

9. Installing ASP.NET MVC 4

After installing the Windows Azure tools, Kean suggests installing MVC 4 beta for Visual Studio 2010.

Finally, my Visual Studio installation is enhanced like this:

10. Implementing an ASP.NET Web Service

I created a new ASP.NET MVC 4 Web Application using the wizard presented by Visual Studio > New > Project > New Project dialogue.

I compiled it and hit F5 to debug it in the browser, which shows the default web-page provided in the boilerplate project:

I have done nothing yet to implement any API, but I can still provide some input data and use the debugger to explore where it ends up in my new project.

Simply replace the original URL displayed in the address bar, in my case 'http://localhost:1574', with an address including some input data, such as 'http://localhost:1574/api/values'. This triggers a breakpoint in the ValuesController Get method taking no arguments:

  // GET api/values
  public IEnumerable<string> Get()
  {
    return new string[] { "value1", "value2" };
  }

The result returned to the browser is an XML document containing the list of predefined values:

Providing an integer id as an additional argument, i.e. in this case as an additional node in the URL path, e.g. 'http://localhost:1574/api/values/12345', triggers the breakpoint in the next overload of the Get method, taking an integer input argument:

  // GET api/values/5
  public string Get( int id )
  {
    return "value";
  }

This time, the result is an XML document containing the one single value specified:

I cannot specify an arbitrary string argument, such as 'jeremy', since the default implementation expects integer id values only:

11. Enabling a Non-numerical Id in the URL

Realising that it will be hard for me to encode the mobile device location into a simple integer, I worked really hard to find a way to pass in a string via the URL.

After extensive research, I finally found a solution in two simple steps:

1. Specify non-standard constraints in the WebApiConfig implementation:

  public static class WebApiConfig
  {
    public static void Register( HttpConfiguration config )
    {
      config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional },
        constraints: new { id = "[0-9a-z]+" }
      );
    }
  }

This important solution is not explicitly pointed out, only sort of hinted at in the article by Mike Wasson on ASP.NET routing and action selection, where it just says that you can "provide constraints, which restrict how a URI segment can match a placeholder". Anyway, this modification finally allows me to enter non-numerical characters in the 'id' part of the URL.

2. The modified constraints triggered an error when executing the application, however, because my ApiController implementation only provides a Get method taking an int argument.

I removed that and replaced it by one taking a string instead:

  public string Get( string id )
  {
    return string.Format(
      "The room containing the input location "
      + "'{0}' is still being determined...", 
      id );
  }

While making these modifications, I also renamed my controller from ValuesController to RoomController.

Now I can pass in a string through the URL and receive the expected result:

I don't know whether I ever previously needed such a long time to learn how to change such a small number of lines of code.

Anyway, now I have more control over my URL argument passing, and can start thinking about an effective format to pass in the mobile device location value and other data.

12. Thoughts on the Web Service Grammar

Please excuse my rather unstructured gung-ho approach. I am thinking about what to implement and how to do so at the same time. Sorry about that. Here goes anyway. More elegantly, I might also simply say that this is work in progress, on all levels.

Now that we have some infrastructure in place, let me take a step back again and consider what I really want to achieve. Basically, I want to query the system for the room containing a given location. In order to do so, I also need to be able to first specify the room data. Let's take a look at the input required for that.

Each room resides on a level. I could specify the levels anew each time I specify a room. A cleaner approach would be to first specify all the levels, supplying data such as their name and elevation, and returning a simple integer id for each. Then I can use the level id when defining the room, which would help avoid a lot of level data repetition.

Once defined, it would also be nice to be able to query the system for the data it contains. It might be useful to retrieve lists of all levels and rooms. For each room, the room polygons could be returned as a list of points.

We could implement rendering to SVG, e.g. given an individual room or an entire level, return an SVG file displaying all its room polygons.

And of course the most basic functionality that this whole exercise is targeted at: given a specific level and location point, return the room containing it.

How can we define a grammar to support this functionality?

Here is a preliminary draft of a suggestion using the following notation: I don't really like those horrible % sign escape codes commonly used in URL arguments.

• I – an integer number, e.g. 342.
• L – an integer level id, i.e. the same as I.
• R – a real number, e.g. 1.234. Might be encoded in the URL as 1p234.
• E – an elevation, i.e. the same as R.
• P – a 3D point, i.e. a comma-separated list of three real numbers, e.g. "R,R,R"; to encode this in a URL, we might want to use something like "RcRcR", i.e. "1p23c4p56c7p89".

With that notation, we might consider operations such as the following:

• levels – list all levels with their id, name and elevation.
• rooms – list all rooms with their level, id and name.
• rooms-L – list all rooms on the given level specified by id integer id N.
• level-add-name-elevation
• room-add-L ...

Actually, I will not even finish this list, just go ahead and start implementing some more right away. Maybe I'll get around to completing and cleaning it up once I know better what I really want.

13. Adding a Levels Controller

In starting to write the grammar and list of actions above, I immediately realise that it would be nice to have more than one controller, so that I can specify different more or less meaningful text snippets in my URL command.

At least I am pretty sure that I would like to be able to use the word 'levels' as well as 'room' or 'rooms', so let's add a LevelsController and see whether that works.

Here are the steps:

• Visual Studio solution explorer > RoomPolygon project > Controllers > right click for context menu > Add > Controller... > LevelsController.
• Change the parent class from 'Controller' to 'ApiController'.
• Replace the default Controller method Index by the ApiController methods Get, Post, Put and Delete, as we have them in the RoomController, which was based on the default whatever-it-was controller in the new project template.

Very simple.

I am not doing everything the way the system expects, though, because my Get() method with no arguments is never called, and trying to call the service with a URL ending in just "api/levels" causes an error. I must specify an id, maybe because my constraints require a non-empty string for the id.

I implemented code in my Get method taking the id argument to respond to the id "all" with a list of all levels.

Here is the resulting code with a dummy level class definition and a list of dummy level entries to play with:

  class Level
  {
    public string Name { get; set; }
    public double Elevation { get; set; }
 
    public Level( string name, double elevation )
    {
      Name = name;
      Elevation = elevation;
    }
 
    public override string ToString()
    {
      return Name + ", " 
        + Elevation.ToString( "0.###" );
    }
  }
 
  public class LevelsController : ApiController
  {
    static List<Level> _levels = new List<Level>()
    {
      new Level ( "Level 1", 12.345 ),
      new Level ( "Level 2", 67.89 )
    };
 
    // GET api/levels
    public IEnumerable<string> Get()
    {
      return new string[] { 
        "1: Level 1, 12.345", 
        "2: Level 2, 67.89" };
    }
 
    public string Get( string id )
    {
      if( id.ToLower().Equals( "all" ) )
      {
        return Get().Aggregate<string>( 
          ( current, next ) 
            => current + ", " + next );
      }
      try
      {
        int i = int.Parse( id );
        if( 0 > i )
        {
          return string.Format( 
            "Invalid negative level id '{0}'", 
            id );
        }
        if( _levels.Count <= i )
        {
          return string.Format( 
            "Invalid out-of-range level id '{0}'", 
            id );
        }
        return _levels[i].ToString();
      }
      catch( Exception ex )
      {
        return string.Format( 
          "Invalid level id '{0}': {1}", 
          id, ex.Message );
      }
    }
 
    // POST api/levels
    public void Post( [FromBody]string value )
    {
    }
 
    // PUT api/levels/5
    public void Put( int id, [FromBody]string value )
    {
    }
 
    // DELETE api/levels/5
    public void Delete( int id )
    {
    }
  }

With that in place, I can now run my ASP.NET RoomPolygon application in the debugger and provide test URLs to receive the following XML results:

• http://localhost:1574/api/levels/all –

  <string>1: Level 1, 12.345, 2: Level 2, 67.89</string>
  

• http://localhost:1574/api/levels/1 –

  <string>Level 2, 67.89</string>
  

I should probably revisit the ASP.NET tutorial, though, and understand the implementation of the Get method with no argument, as well as the Post, Put and Delete methods.

14. Summary and Next Steps

I completed my education day working through these thirteen (rather arbitrary) steps. Let's stop at this special number and consider what has been achieved.

We have painted an interesting scenario, albeit possibly a little bit ahead of its time.

We have considered some architectural underpinnings and possible implementation approaches, and looked at some possible interesting bits and pieces of infrastructure and support, such as SVG.

We have installed support for and created an MVC 4 Azure web service, and made some useful modifications to it as a proof of concept for populating it with data from the Revit BIM as well as querying the service from the mobile device.

What to do next?

Well, we still have not implemented anything at all to run on the mobile device, so that is an important next step.

We need to implement the Revit add-in to call the web service and populate the level and room information in the cloud.

The web service itself needs to be implemented to receive the data from the BIM, save it in efficient internal data structures or a database, and reply to queries from the mobile device, possibly including requests for a graphical representation, potentially based on SVG.

As hinted, I am not completely happy with my understanding of the ASP.NET functionality yet. I need to revisit that, and maybe restart from scratch with a better understanding.

It would help to first understand it workings in more depth, plan the full required functionality and how it should be made accessible, and only then start implementing :-)

Oh yes, the web service needs to be deployed to the cloud, as well.

Looks like I have enough material lined up for another couple of interesting education days.

Before I end, here is the initial version 0.0.1.0 of my skeleton web service implementation, in case it is of interest to anyone.

It handles the grammar outlined above but does not execute any actions on the requests yet, beyond echoing them in the XML strings returned.

Picking Two Points Consecutively

Here is a question on picking points while interacting with a modeless dialogue:

Question: I want to pick two points consecutively using PickPoint.

I am using a modeless dialog, and have a section of code that is called when a button is pressed.

However, after picking the first point, an exception is thrown saying "The user aborted the pick operation".

Do you have a solution for this?

Answer: I implemented a sample application providing an external command PickTwoPoints for you to demonstrate one possible solution.

I use the following code to generate and display a modeless dialogue to the user before the picking is initiated:

  Form DisplayModelessForm( IWin32Window owner )
  {
    System.Windows.Forms.Form form
      = new System.Windows.Forms.Form();
    form.Size = new Size( 300, 100 );
    form.Text = "Pick Two Points Modeless Form";
    form.Show( owner );
    return form;
  }

The form is initially displayed, then hidden again before calling PickPoint.

As always when displaying a modeless form, I define its owner window to be the Revit main frame.

I use my JtWindowHandle wrapper class to convert the IntPtr returned by the Autodesk.Windows.ComponentManager ApplicationWindow property to an IWin32Window, which can be passed in to the form Show method to set its owner:

  /// <summary>
  /// Wrapper class for converting 
  /// IntPtr to IWin32Window.
  /// </summary>
  public class JtWindowHandle : IWin32Window
  {
    IntPtr _hwnd;
 
    public JtWindowHandle( IntPtr h )
    {
      Debug.Assert( IntPtr.Zero != h,
        "expected non-null window handle" );
 
      _hwnd = h;
    }
 
    public IntPtr Handle
    {
      get
      {
        return _hwnd;
      }
    }
  }

The external command Execute method performs the following steps:

• Determine the main Revit application window handle.
• Display the dynamically generated modeless form.
• Hide the form.
• Select the two points.
• Process the two resulting points, in this case by displaying them in the Visual Studio debug output window.
• Redisplay the modeless form.
• Close and terminate.

Here is the whole resulting Execute method mainline code implementing this:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  IWin32Window revit_window
    = new JtWindowHandle(
      ComponentManager.ApplicationWindow );
 
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Selection sel = uidoc.Selection;
 
  using( Form form = DisplayModelessForm( 
    revit_window ) )
  {
    form.Hide();
 
    try
    {
      XYZ p = sel.PickPoint( "Point 1" );
 
      XYZ q = sel.PickPoint( "Point 2" );
 
      Debug.Print( string.Format(
        "The two points you selected are {0} and {1}.",
        PointString( p ), PointString( q ) ) );
    }
    catch( Exception e )
    {
      Debug.Print( e.Message );
    }
 
    form.Show();
  }
  return Result.Succeeded;
}

As it now stands, this can obviously be packaged in an external command using read-only transaction mode, since the database is not affected in any way.

Here is PickTwoPoints.zip containing the complete source code, entire Visual Studio solution and add-in manifest of the PickTwoPoints external command.

Automatically Store Revit Model as Blob in the Cloud

On the cloud and mobile front, Saikat Bhattacharya published an article describing his GbXmlCloudSync add-in demonstrating how to use the DocumentSaved event and the Windows Azure blob storage service to automatically upload each new version of a Revit model to the cloud, for instance for environmental analysis.

This is part of his Windows Azure experiential learning series.

Autodesk 360 Videos for MEP and Structure

On the same topic, here are two new short videos about the use of Autodesk BIM 360 for MEP and structural engineers.

For MEP, this can provide insight into energy consumption, improve visualisation, photorealistic presentation, and CFD simulation. Structural enhancement possibilities include access to simulation tools for more informed decisions, conducting computational heavy simulation earlier and more often, and optimising structural workflows with static and finite analysis tools.

This could be the first step of a move towards the next generation of BIM for anyone, anywhere, at any time, with access to intelligent, model-based workflows through a broad range of cloud-based services providing mobility, accessibility, and infinite computing power.

Here is a freshly published 1 minute and 20 seconds video on Autodesk BIM 360 for MEP engineers:

Here is an even more succinct 1 minute video on Autodesk BIM 360 for structural engineers:

According to some, start-ups rejoice at the reduced simulation costs.

Apollonian Sphere Packing via Web Service and AVF

Spheres are not as common as planar faceted objects in the architectural domain. In spite of that, this week has been the week of the spheres, after looking at how to generate spherical solids, display them using AVF, and use them for geometrical proximity filtering.

We'll round this off now by displaying lots of spheres. A convenient and interesting way to generate a large number of them is to use Kean Walmsley's Apollonian gasket and sphere packing web service to fill a sphere with solid spheres (project overview).

To give you a quick first impression of what it is all about, here are some views of different levels of Apollonian sphere packing using Revit transient solids generated by the GeometryCreationUtilities class and its CreateRevolvedGeometry method and displayed in the Revit graphics area using the Analysis Visualization Framework AVF. Apollonian packing with three levels:

Apollonian packing with five levels:

Apollonian packing with seven levels:

Retrieval and display of this data in Revit requires the following steps and functionality, listed here in the order of their implementation in the source code:

• String formatting and parsing
• Web service request and JSON deserialisation
• AVF Functionality
• Spherical solid creation and mainline putting it all together

I'll simply present these sections of code with some comments on each.

String Formatting and Parsing

The string formatting and parsing is required both to obtain input data from the user and to present some timing and statistical results at the end.

The input to the sphere packing algorithm web service consists of an outer sphere radius and the number of steps to execute, which varies from 2 upwards, where 10 is a pretty high number.

I implemented a little .NET form to request this input from the user together with a centre point defining the location in the Revit model to display the packing:

The following trivial methods are used to parse this input data and format the timing results:

  /// <summary>
  /// Return a string for a real number
  /// formatted to two decimal places.
  /// </summary>
  public static string RealString( double a )
  {
    return a.ToString( "0.##" );
  }
 
  /// <summary>
  /// Return an integer parsed 
  /// from the given string.
  /// </summary>
  static int StringToInt( string s )
  {
    return int.Parse( s );
  }
 
  /// <summary>
  /// Return a real number parsed 
  /// from the given string.
  /// </summary>
  static double StringToReal( string s )
  {
    return double.Parse( s );
  }
 
  /// <summary>
  /// Return an XYZ point or vector 
  /// parsed from the given string.
  /// </summary>
  static XYZ StringToPoint( string s )
  {
    s.TrimStart( new char[] { '(', ' ' } );
    s.TrimEnd( new char[] { ')', ' ' } );
    string[] a = s.Split( new char[] { ',', ' ' } );
    return ( 3 == a.Length ) 
      ? new XYZ( 
          StringToReal( a[0] ), 
          StringToReal( a[1] ), 
          StringToReal( a[2] ) )
      : null;
  }

All trivial stuff, and still it helps to have it nicely sorted.

Web service request and JSON deserialisation

The use of Kean's sphere packing web service is straightforward.

You send it an HTTP request, it returns results in JSON format, you unpack them, and Bob's your uncle.

Kean describes it in detail and presents the source code implementing it in his discussion of consuming data from a restful web service.

It was originally designed for use in AutoCAD.NET. I simply grabbed his code and reuse it completely unchanged:

  static dynamic ApollonianPackingWs( 
    double r, 
    int numSteps, 
    bool circles )
  {
    string json = null;
 
    // Call our web-service synchronously (this 
    // isn't ideal, as it blocks the UI thread)
 
    HttpWebRequest request =
      WebRequest.Create(
        //"http://localhost:64114/api/"
        "http://apollonian.cloudapp.net/api/"
        + ( circles ? "circles" : "spheres" )
        + "/" + r.ToString()
        + "/" + numSteps.ToString()
      ) as HttpWebRequest;
 
    // Get the response
 
    using(
      HttpWebResponse response =
        request.GetResponse() as HttpWebResponse
      )
    {
      // Get the response stream
 
      StreamReader reader =
        new StreamReader( 
          response.GetResponseStream() );
 
      // Extract our JSON results
 
      json = reader.ReadToEnd();
    }
 
    if( !String.IsNullOrEmpty( json ) )
    {
      // Use our dynamic JSON converter to 
      // populate/return our list of results
 
      var serializer = new JavaScriptSerializer();
      serializer.RegisterConverters(
        new[] { new DynamicJsonConverter() }
      );
 
      // We need to make sure we have enough space 
      // for our JSON, as the default limit may well 
      // get exceeded
 
      serializer.MaxJsonLength = 50000000;
 
      return serializer.Deserialize( json, 
        typeof( List<object> ) );
    }
    return null;
  }

AVF Functionality

The code implementing AVF functionality has also already been presented and discussed elsewhere. The last use I made of it was for the initial sphere display using AVF.

All I did here was to replace the PaintSolid method used there to handle multiple solids. I implemented this trivial helper class to associate a solid with a level in order to represent the levels in different colours in the visualisation:

  class SolidAndLevel
  {
    public Solid Solid { get; set; }
    public int Level { get; set; }
  }

Here is the code to create an AVF display style, get or create a SpatialFieldManager, set up an analysis result schema, and display the spherical solids using PaintSolids, taking a list of SolidAndLevel instances as input:

  void CreateAvfDisplayStyle(
    Document doc,
    View view )
  {
    using( Transaction t = new Transaction( doc ) )
    {
      t.Start( "Create AVF Style" );
      AnalysisDisplayColoredSurfaceSettings
        coloredSurfaceSettings = new
          AnalysisDisplayColoredSurfaceSettings();
 
      coloredSurfaceSettings.ShowGridLines = false;
 
      AnalysisDisplayColorSettings colorSettings
        = new AnalysisDisplayColorSettings();
 
      AnalysisDisplayLegendSettings legendSettings
        = new AnalysisDisplayLegendSettings();
 
      legendSettings.ShowLegend = false;
 
      AnalysisDisplayStyle analysisDisplayStyle
        = AnalysisDisplayStyle
          .CreateAnalysisDisplayStyle( doc,
            "Paint Solid", coloredSurfaceSettings,
            colorSettings, legendSettings );
 
      view.AnalysisDisplayStyleId
        = analysisDisplayStyle.Id;
 
      t.Commit();
    }
  }
 
  static int _schemaId = -1;
 
  void PaintSolids(
    Document doc,
    IList<SolidAndLevel> solids )
  {
    Application app = doc.Application;
 
    View view = doc.ActiveView;
 
    if( view.AnalysisDisplayStyleId
      == ElementId.InvalidElementId )
    {
      CreateAvfDisplayStyle( doc, view );
    }
 
    SpatialFieldManager sfm
      = SpatialFieldManager.GetSpatialFieldManager(
        view );
 
    if( null == sfm )
    {
      sfm = SpatialFieldManager
        .CreateSpatialFieldManager( view, 1 );
    }
 
    if( _schemaId != -1 )
    {
      IList<int> results
        = sfm.GetRegisteredResults();
 
      if( !results.Contains( _schemaId ) )
      {
        _schemaId = -1;
      }
    }
 
    if( _schemaId == -1 )
    {
      AnalysisResultSchema resultSchema
        = new AnalysisResultSchema(
          "PaintedSolids", "Description" );
 
      _schemaId = sfm.RegisterResult( resultSchema );
    }
 
    foreach( SolidAndLevel sl in solids )
    {
      FaceArray faces = sl.Solid.Faces;
      Transform trf = Transform.Identity;
 
      foreach( Face face in faces )
      {
        int idx = sfm.AddSpatialFieldPrimitive(
          face, trf );
 
        IList<UV> uvPts = new List<UV>( 1 );
 
        uvPts.Add( face.GetBoundingBox().Min );
 
        FieldDomainPointsByUV pnts
          = new FieldDomainPointsByUV( uvPts );
 
        List<double> doubleList 
          = new List<double>( 1 );
 
        doubleList.Add( sl.Level );
 
        IList<ValueAtPoint> valList
          = new List<ValueAtPoint>( 1 );
 
        valList.Add( new ValueAtPoint( doubleList ) );
 
        FieldValues vals = new FieldValues( valList );
 
        sfm.UpdateSpatialFieldPrimitive(
          idx, pnts, vals, _schemaId );
      }
    }
  }

Spherical Solid Creation and Mainline

The spherical solid creation is absolutely unchanged from the discussion on Monday, so I can get right down to the mainline Execute method putting it all together. It

• Checks that we are in a 3D view.
• Prompts the user for the input data.
• Calls the web service and extracts the results.
• Creates the spherical solids.
• Paints the solids.

Each of the steps is timed, the spheres are counted, and the final results are presented, looking like this for three levels:

For five levels:

For seven levels:

Revit actually required some additional time on my system to complete and return from the command after these messages were displayed, and mostly that took longer than the entire command execution itself.

Here is the Execute mainline implementing these steps:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    CreationApp creapp = app.Create;
    Document doc = uidoc.Document;
 
    if( !(doc.ActiveView is View3D) )
    {
      message 
        = "Please run this commahnd in a 3D view.";
 
      return Result.Failed;
    }
 
    XYZ centre = XYZ.Zero;
    double radius = 100.0;
    int steps = 3;
 
    using( Form1 f = new Form1() )
    {
      if( DialogResult.OK != f.ShowDialog() )
      {
        return Result.Cancelled;
      }
      centre = StringToPoint( f.GetCentre() );
      radius = StringToReal( f.GetRadius() );
      steps = StringToInt( f.GetLevel() );
    }
 
    // Time the web service operation
 
    Stopwatch sw = Stopwatch.StartNew();
 
    dynamic res = ApollonianPackingWs( 
      radius, steps, false );
 
    sw.Stop();
 
    double timeWs = sw.Elapsed.TotalSeconds;
 
    // Create solids, going through our "dynamic"
    // list, accessing each property dynamically
 
    sw = Stopwatch.StartNew();
 
    List<SolidAndLevel> solids 
      = new List<SolidAndLevel>();
 
    Dictionary<int, int> counters 
      = new Dictionary<int, int>();
 
    foreach( dynamic tup in res )
    {
      double rad = System.Math.Abs( (double) tup.R );
 
      Debug.Assert( 0 < rad, 
        "expected positive sphere radius" );
 
      XYZ cen = new XYZ( (double) tup.X, 
        (double) tup.Y, (double) tup.Z );
 
      int lev = tup.L;
 
      Solid s = CreateSphereAt( creapp, cen, rad );
 
      solids.Add( new SolidAndLevel { 
        Solid = s, Level = lev } );
 
      if( !counters.ContainsKey( lev ) )
      {
        counters[lev] = 0;
      }
      ++counters[lev];
    }
 
    sw.Stop();
 
    double timeSpheres = sw.Elapsed.TotalSeconds;
 
    // Set up AVF and paint solids
 
    sw = Stopwatch.StartNew();
 
    PaintSolids( doc, solids );
 
    sw.Stop();
 
    double timeAvf = sw.Elapsed.TotalSeconds;
 
    int total = 0;
    string counts = string.Empty;
    List<int> keys = new List<int>( counters.Keys );
    keys.Sort();
    foreach( int key in keys )
    {
      if( 0 < counts.Length )
      {
        counts += ",";
      }
      int n = counters[key];
      counts += n.ToString();
      total += n;
    }
 
    string report = string.Format( 
      "{0} levels retrieved with following sphere "
      + "counts: {1} = total {2}; times in seconds "
      + "for web service {3}, sphere creation {4} "
      + "and AVF {5}.",
      counters.Count, counts, total, 
      RealString( timeWs ), 
      RealString( timeSpheres ), 
      RealString( timeAvf ) );
 
    TaskDialog.Show( "Apollonian Packing", report );
 
    return Result.Succeeded;
  }

Since Kean did all the web service implementation and JSON extraction work for me, it all boiled down to just putting together a few ready-made components. Thank you, Kean!

Please refer to Kean's project overview for all the nitty-gritty background details.

Here is Apollonian.zip containing the complete source code, Visual Studio solution and add-in manifest for this external command.

Anyway, this should provide enough spheres for this week and keep us all happy and occupied over the weekend.

Categories Collection Item Accessor Fails

The document settings categories collection Item property returns null for certain built-in categories, and even throws an exception for certain others. You should be aware of this.

I mentioned a related issue back in the Revit 2011 timeframe, describing The Building Coder CmdCategories sample command.

Still, this is a bit unexpected and has caused issues for several developers.

Here are some examples:

Question 1: For some reason I cannot obtain the category for stacked walls, e.g. using

  Dim cat As Category = Doc.Settings.Categories
    .Item(BuiltInCategory.OST_StackedWalls)

This call returns nothing even though I have stacked walls in my document. I can also find the BuiltinCategory.OST_StackedWalls using RevitLookup.

Should I be looking somewhere else?

Question 2: I am adding several parameters through

  doc.ParameterBindings.Insert(
    information, caseTying, bipgroup );

Sometimes I get an error, even though the parameters all seem OK.

The stack trace says NullReferenceException in BindingMap.Insert.

What is causing this?

Here is a code snippet demonstrating the problem:

  DefinitionFile sharedParametersFile
    = app.OpenSharedParameterFile();
 
  DefinitionGroup group = sharedParametersFile
    .Groups.Create( "Reinforcement" );
 
  Definition def = group.Definitions.Create(
    "ReinforcementParameter", ParameterType.Text );
 
  List<BuiltInCategory> bics
    = new List<BuiltInCategory>();
 
  //bics.Add(BuiltInCategory.OST_AreaRein);
  //bics.Add(BuiltInCategory.OST_FabricAreas);
  //bics.Add(BuiltInCategory.OST_FabricReinforcement);
  //bics.Add(BuiltInCategory.OST_PathRein);
  //bics.Add(BuiltInCategory.OST_Rebar);
 
  bics.Add( BuiltInCategory
    .OST_IOSRebarSystemSpanSymbolCtrl );
 
  CategorySet catset = new CategorySet();
 
  foreach( BuiltInCategory bic in bics )
  {
    catset.Insert(
      doc.Settings.Categories.get_Item( bic ) );
  }
 
  InstanceBinding binding
    = app.Create.NewInstanceBinding( catset );
 
  doc.ParameterBindings.Insert( def, binding,
    BuiltInParameterGroup.PG_CONSTRUCTION );

Answer: The first issue is due to OST_StackedWalls being marked 'Hidden to User', causing certain internal methods to return false. As a final result, the Categories Item accessor returns null.

'Hidden to User' means that the user interface to Object Styles, Visibility/Graphics, and Export Layers will not include these categories.

It does not mean that the categories are hidden everywhere in the product. Some features get a specific category from an element and display its name. For example, the status prompt displays the category of the element that the mouse is hovering over, and the Selection Filter dialog displays the categories of selected elements. This works because other methods return all categories regardless of the 'Hidden to User' flag.

Aside from OST_StackedWalls, here are some other categories that may correspond to real elements that users can see, select, and whose category name may appear:

• OST_Reveals
• OST_ArcWallRectOpening
• OST_SWallRectOpening
• OST_SitePropertyLineSegment
• OST_RvtLinks
• OST_LegendComponents
• OST_ConnectorElem

Some features also display lists of categories that don't come from the CategoryTableInterface methods. Schedules, project parameters, the Family Category and Parameters dialog are examples. Typically those can also include 'Hidden to User' categories. For example, OST_SitePropertyLineSegment is a schedulable category despite being 'Hidden to User'.

In some cases it may be incorrect for the API to prevent people from working with 'Hidden to User' categories. Of course any APIs for category-related features should have proper validation so that people can only use appropriate categories. For example, APIs for category visibility, project parameters, and schedules should restrict which categories can be used for those features, just like the UI does. We have to be careful about exposing 'Hidden to User' categories without checking other APIs for proper validation. For example, the project parameters API may allow more categories that it should.

I expanded The Building Coder samples CmdCategories external command to determine and display a list of all the built-in categories causing the Categories.Item property to either return null or throw an exception. Here is the code that demonstrates that:

  Array bics = Enum.GetValues(
    typeof( BuiltInCategory ) );
 
  int nBics = bics.Length;
 
  Debug.Print( "{0} built-in categories and the "
    + "corresponding document ones:", nBics );
 
  Category cat;
  string s;
 
  List<BuiltInCategory> bics_null
    = new List<BuiltInCategory>();
 
  List<BuiltInCategory> bics_exception
    = new List<BuiltInCategory>();
 
  foreach( BuiltInCategory bic in bics )
  {
    try
    {
      cat = categories.get_Item( bic );
 
      if( null == cat )
      {
        bics_null.Add( bic );
        s = "<null>";
      }
      else
      {
        s = string.Format( "{0} ({1})",
          cat.Name, cat.Id.IntegerValue );
      }
    }
    catch( Exception ex )
    {
      bics_exception.Add( bic );
 
      s = ex.GetType().Name + " " + ex.Message;
    }
    Debug.Print( "  {0} --> {1}", 
      bic.ToString(), s );
  }
 
  int nBicsNull = bics_null.Count;
  int nBicsException = bics_exception.Count;
 
  TaskDialog dlg = new TaskDialog(
    "Hidden Built-in Categories" );
 
  s = string.Format(
    "{0} categories obtained from the Categories collection;\r\n"
    + "{1} built-in categories;\r\n"
    + "{2} built-in categories retrieve null result;\r\n"
    + "{3} built-in categories throw an exception:\r\n",
    nCategories, nBics, nBicsNull, nBicsException );
 
  Debug.Print( s );
 
  dlg.MainInstruction = s;
 
  s = bics_exception
    .Aggregate<BuiltInCategory, string>(
      string.Empty,
      ( a, bic ) => a + "\n" + bic.ToString() );
 
  Debug.Print( s );
 
  dlg.MainContent = s;
 
  dlg.Show();

This is the resulting output in an empty architectural project reporting the count of document categories, built-in categories, and built-in categories for which a document category cannot be retrieved, either because the call the Categories.Item returns null or throws an exception:

To spell it out in full text:

• 259 categories obtained from the Categories collection;
• 897 built-in categories;
• 358 built-in categories retrieve null result;
• 12 built-in categories throw an exception:
  • OST_FurnitureHiddenLines
  • OST_SplitterProfile
  • OST_HostTemplate
  • OST_MassFaceSplitter
  • OST_MassCutter
  • OST_ZoningEnvelope
  • OST_StairsSupports
  • OST_InstanceDrivenLineStyle
  • OST_CurtainGridsSystem
  • OST_StairsStringerCarriage
  • OST_IOSNotSilhouette
  • OST_InvisibleLines

The complete lists of built-in categories for which no corresponding document category can be retrieved are logged to the Visual Studio debug output window. They obviously depend on the document that you run this command in.

You should probably run it yourself in the documents you are working with to be aware of what is going on. In any case, all code accessing the Categories.Item property with untested built-in categories needs to implement appropriate handling of these conditions.

Here is the updated version 2013.0.99.1 of The Building Coder samples including the expanded version of the CmdCategories external command displaying the list of hidden built-in categories.

Addendum: Saikat presented another example of an inaccessible category, the Profiles category OST_ProfileFamilies.

Brute Force Computing

I stumbled across this interesting article on brute force computing explaining one interesting aspect of cloud based computing and access to huge amounts of computing power.

One fact I was totally unaware of, and that had me a bit surprised in the past year or two, is that "brute force computing is behind Google's successful language translation. By comparing thousands of Web pages in different languages to find patterns, in one year Google was able to discern and refine translation better than linguistic theorists had been able to do with their fancy programs for years."

As you of course know, Autodesk offers the Autodesk 360 cloud-based platform providing access to storage, a collaboration workspace, and a fast-growing number of cloud services to help improve design, visualisation, simulation, and work sharing.

Blending Profiles with Different Vertex Counts

Arjen de Pater raised a question on using the NewBlend method that Mikako Harada just addressed:

Question: I want to create a blend with 8 curves in the BottomProfile and 4 curves in the TopProfile.

When I try this the Document.FamilyCreate.NewBlend method throws an ApplicationException saying "Unexpected internal error: code 1. at Autodesk.Revit.Creation.FamilyItemFactory.NewBlend(Boolean isSolid, CurveArray topProfile, CurveArray baseProfile, SketchPlane sketchPlane)".

How can I create such a blend?

Answer: There are some points you need to pay attention to. These points are documented in the page explaining the NewBlend method in Revit API help file RevitAPI.chm file. It also includes sample code to create a blend form:

1. The two profiles should be parallel.
2. Each of the profiles must be planar.
3. If the profile shape is circle or ellipse, it must be split into at least two segments, so that Revit can find vertices to use for mapping the blend.

Once that is clear, you should definitely ensure that you can create the same shape through the user interface, as recommended for debugging form creation. If that fails, then it will fail through the API as well. It may provide you with a more informative error message, though.

Response: Yes, I can create the blend in the UI.

The problem is the different number of curves in the BottomProfile and TopProfile because the NewBlend method lacks a parameter for the VertexConnectionMap.

Answer: Ah. Well, here are two NewSweptBlend samples, which may or may not prove useful.

However, Mikako hopefully provided the ultimate solution by demonstrating blending two profiles with different top and bottom vertex counts.

Creating a ViewPlan in a Family Document

On the topic of Revit API blog posts by my colleagues on the AEC DevBlog, here is another interesting topic brought up by Saikat Bhattacharya:

You can create a new ViewPlan in a family document using the View.Duplicate method taking a ViewDuplicateOption, something that I was not previously aware of.

You cannot use the NewViewPlan method to achieve this in a family document, because it throws an InvalidOperationException, as Saikat explains very clearly.