The Building Coder

Crop 3D View to Room

In case you have heard enough about both climbing and AU and AUv in the last few posts and would prefer to read about the Revit API and nothing but the Revit API, here is something for you. This is based on a recent case handled by Joe Ye and deals with the 3D view crop box and the transformations required to set it up properly, an issue we have never previously looked at.

Question: I would like to set the crop box of a 3D view to correspond to a single room.

Answer: As the 3D view rotates the room, the original bounding box of the plan view will not be suitable to use for the 3D view crop box. Here is an idea to calculate the crop box. Retrieve all the corner point vertex coordinates of the room, and project them onto the plane perpendicular to the 3D view's view direction. This produces projected point coordinates. From these result point coordinates, determine the maximum and minimum X and Y values. From the max and min points, create the 3D view's crop box.

Here are the detailed steps to implement this idea:

• Retrieve all vertex coordinates of the room.
• Project these coordinates to the plane perpendicular to the 3D view's view direction. To do so, create a face perpendicular to the view direction. The projected results can be obtained from the Face.Project method taking an XYZ point argument. For more information, see the Revit API help file RevitAPI.chm for the usage and return value of this method.
• Go through the resulting coordinates and determine the maximum and minimum X and Y coordinate values.
• Use the four values to determine a bounding box:

  BoundingBoxXYZ bb = new BoundingBoxXYZ(); 
  bb.Min = NewXYZ( xMin, yMin, 0 );
  bb.Max = NewXYZ( xMax, yMax, 0 );
  

• Use the bounding box to set the 3D view crop box:

  View3d.CropBox = bb;
  

Actually, after some further investigation, I found a better way to determine the room extents. It is hard to create a solid and make one face of it perpendicular to the view direction.

You can also use the Transform class to calculate the crop box of the 3D view instead.

First, determine the transformation for translating coordinates in the 3D view to the world coordinate system WCS from the View3d.CropBox.Transform property. Then invert it to obtain the transformation to translate model WCS coordinates back to the 3D view coordinates.

Determine the room vertices from its ClosedShell property, and translate them to 3D view coordinates. Find the minimum and maximum X and Y coordinate values as described above and set the 3D view's crop box Max and Min properties using these.

You do need to activate and make the crop box visible to see the effect. You can do so using the Crop View and Show Crop Region buttons in the user interface:

This can also be achieved programmatically using:

  view3d.CropBoxActive = true;
  view3d.CropBoxVisible = true;

So far for Joe's idea. Many thanks to Joe for all the research into this!

I implemented a new Building Coder sample command CmdCropToRoom to test and demonstrate this. In order to show how the crop box can be set to various different regions in the model, it iterates over all the rooms in the model and sets the crop box of the current 3D view to the next room in the sequence on each call. We retrieve a list of all rooms in the model using doc.get_Elements:

List<RvtElement> rooms = new List<RvtElement>();
int n = doc.get_Elements( typeof( Room ), rooms );

To loop through the rooms in the model and step to the next room in the list on each invocation of the command, we use their index in the list of elements returned by this call. The last index used is stored in a static variable _i, and the method BumpRoomIndex is used to increment it by one on each call:

static int _i = -1;

static int BumpRoomIndex( int room_count )
{
  ++_i;
 
  if( _i >= room_count )
  {
    _i = 0;
  }
  return _i;
}

The next room to crop the view to is selected using

Room room = (0 < n) 
  ? rooms[BumpRoomIndex( n )] as Room 
  : null;

Here is the entire code of the CmdCropToRoom external command Execute method which crops the current 3D view to the next room extents:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
View3D view3d = doc.ActiveView as View3D;
 
if( null == view3d )
{
  message = "Please activate a 3D view"
    + " before running this command.";
 
  return CmdResult.Failed;
}
 
// get the 3d view crop box:
 
BoundingBoxXYZ bb = view3d.CropBox;
 
// get the transform from the current view 
// to the 3D model:
 
Transform transform = bb.Transform;
 
// get the transform from the 3D model 
// to the current view:
 
Transform transformInverse = transform.Inverse;
 
// get all rooms in the model:
 
List<RvtElement> rooms = new List<RvtElement>();
int n = doc.get_Elements( typeof( Room ), rooms );
 
Room room = (0 < n) 
  ? rooms[BumpRoomIndex( n )] as Room 
  : null;
 
if( null == room )
{
  message = "No room element found in project.";
  return CmdResult.Failed;
}
 
// collect all vertices of room closed shell 
// to determine its extents:
 
GeoElement e = room.ClosedShell;
XYZArray vertices = app.Create.NewXYZArray();
 
foreach( GeometryObject o in e.Objects )
{
  if( o is Solid )
  {
    // iterate over all the edges of all solids:
 
    Solid solid = o as Solid;
 
    foreach( Edge edge in solid.Edges )
    {
      foreach( XYZ p in edge.Tessellate() )
      {
        // collect all vertices, 
        // including duplicates:
 
        vertices.Append( p );
      }
    }
  }
}
 
XYZArray verticesIn3dView 
  = app.Create.NewXYZArray();
 
foreach( XYZ p in vertices )
{
  verticesIn3dView.Append( 
    transformInverse.OfPoint( p ) );
}
 
// ignore the Z coorindates and find the 
// min and max X and Y in the 3d view:
 
double xMin = 0, yMin = 0, xMax = 0, yMax = 0;
 
bool first = true;
foreach( XYZ p in verticesIn3dView )
{
  if( first )
  {
    xMin = p.X;
    yMin = p.Y;
    xMax = p.X;
    yMax = p.Y;
    first = false;
  }
  else
  {
    if( xMin > p.X )
      xMin = p.X;
    if( yMin > p.Y )
      yMin = p.Y;
    if( xMax < p.X )
      xMax = p.X;
    if( yMax < p.Y )
      yMax = p.Y;
  }
}
 
// grow the crop box by one twentieth of its 
// size to include the walls of the room:
 
double d = 0.05 * ( xMax - xMin );
xMin = xMin - d;
xMax = xMax + d;
 
d = 0.05 * ( yMax - yMin );
yMin = yMin - d;
yMax = yMax + d;
 
bb.Max = new XYZ( xMax, yMax, bb.Max.Z );
bb.Min = new XYZ( xMin, yMin, bb.Min.Z );
 
view3d.CropBox = bb;
 
// change the crop view setting manually or 
// programmatically to see the result:
 
view3d.CropBoxActive = true;
view3d.CropBoxVisible = true;
 
return CmdResult.Succeeded;

Here is a minimal model with two rooms to test this command:

Running the external command defined by CmdCropToRoom sets the 3D view crop box to the extents of the first room:

Running it another time increments the current room index and sets the 3D view crop box to its extents instead:

Here is version 1.1.0.56 of the complete Building Coder sample source code and Visual Studio solution including the new command.

There are a number of conceivable enhancements to this code. One of the most obvious would be to eliminate duplicate vertices before applying the inverse transformations and searching for the minimum and maximum coordinate values. We did implement some useful functionality for doing that with the XyzEqualityComparer class and GetVertices method in the nested instances geometry retrieval. It might also be possible to use generic collections such as List<XYZ> instead of XYZArray for the original and transformed vertices, and generic .NET functionality to apply the transformation and determine the max and min coordinate values. We left out such enhancements in this case for the sake of clarity, but if you have any suggestions to make, please feel free to do so.

Handle Category Name Change

Here is a little note I wrote sitting in Washington Dulles airport and did not get around to posting until now, to point out the importance of using language independent category comparisons:

Question: Apparently at least one category name changed in the German version of Revit from 2009 to 2010:

• Revit 2009: "Tragende Stützen"
• Revit 2010: "Tragwerksstützen"

We rely on category names for mapping purposes. In this case we discovered the change that was causing problems for us, but I am worried that there may be other similar changes that I also need to be aware of. Is there any way to use a language independent identifier that will never change? I very much hope to find a way to identify categories in a language independent fashion.

Answer: You can use the built-in category enumeration to make your code language independent when working with categories. We looked at this and related topics in the discussions on category comparison and later explored it further for the model element selection, which we recently enhanced to handle a set of multiple categories using a list of built-in category enumeration values stored in _bics_to_skip and the helper method SkipThisBic to compare them all with a given value from a candidate element.

Visible Elements

I am sitting here cramped up in an economy seat crossing the Atlantic Ocean as I write this. I should urgently be practicing and preparing for my sessions at AU, but somehow it feels as if writing a blog post requires slightly less space, so here goes. I would also like to answer some pending comments, but cannot right now due to lack of Internet access...

After revisiting the topic of selecting all model elements in the last post, there is one more important and interesting issue to take into account to determine all the visible model elements. In that post, we made use of element filtering instead of an iterator over all elements and eliminated a number of unwanted element types and categories. Once we have thus whittled away the non-model elements, there are still several possibilities to hide elements in a given view through the user interface. Here are two main methods that can be used to hide elements in a view:

• Hide an individual element.
• Hide an entire category of elements.

To determine whether an element is hidden, we need to check for both of these possibilities. In addition, an element may belong to a subcategory. If so, it may be hidden either because its subcategory or one of its parent categories is hidden.

The Revit SDK sample VisibilityControl demonstrates how to control visibility by category, and the topic of categories and how they are used is covered in detail in section 5.2.1 Category of the developer guide "Revit 2010 API Developer Guide.pdf".

The visibility of an element in a view can be queried using the Element.IsHidden( View ) method, the visibility of a category by the Category.Visible property.

Here is the code of a helper method IsHiddenElementOrCategory which takes all these factors into account and can be used to check whether an element 'e' is hidden in a given view 'v'. It returns true if the given element is hidden in this view, either as an individual element, or because its category or one of its parent categories is hidden:

static bool IsHiddenElementOrCategory(
  Element e,
  View v )
{
  bool hidden = e.IsHidden( v );
 
  if( !hidden )
  {
    Category cat = e.Category;
    while( null != cat && !hidden )
    {
      hidden = !cat.get_Visible( v );
      cat = cat.Parent;
    }
  }
  return hidden;
}

Red Rock Revisited

By the way, some time has passed between starting to write and actually posting this. I arrived safely in Las Vegas, grabbed a rental car, and went off to un-jetlag by spending the night in a sleeping bag in the desert. Rather cold, but not freezing, this time around. Two years ago, it was significantly below freezing and my gallon bottle of water froze solid, all the way down. Last year, it was warmer and moister and had actually rained just before my arrival. This year is the most pleasant to date. Frankly, I prefer the desert to the strip.

I spent my first day here climbing in the Red Rock climbing area with a bunch of crazy guys from Dallas, Texas, namely Karl, Fritz, Gary, Jess and Ellis. We did several easy routes on the Ultraman wall, including Scent of an Ultraman 5.7, Clutch Cargo 5.7 and Science Patrol 5.8.

We met up early next morning again to go the Black Corridor, which I visited in the previous two years as well. I led a number of climbs in the morning including The Cel 50' 5.9, Bon Ez 5.9+, and two of hardest and nicest I've ever done, Heavy Hitter and Friend 40', both 5.10d. The guys from Dallas left to return home at midday and I teamed up with Sonja & Jean-Francois from Quebec in the afternoon to climb two more routes led by Jean-Francois, Crude Street 5.9+ and Dance with a God 5.10a.

I am now sitting in the Barnes and Noble book store on West Charleston Boulevard and gratefully using the free Internet access they provide to finish off and post this. This is the road that I keep going up and down to get to Red Rock.

Solid Material

Here is a simple question with a simple answer on materials and solids:

Question: Is there a way to retrieve the material of the solid geometry object of a Revit Element, like the door leaf of a door element?

Answer: No, I am not aware of any way that a material can be assigned to a solid. The only representation of the solid in the graphical user interface is through its faces, and they can have materials assigned to them. As far as I know, the solid itself has no such property. The only way that I am aware of to determine the material of a solid is through the path Solid > Faces > FaceArray > Item > Face > MaterialElement.

Another short little note on a completely unrelated topic:

Clean Uninstall of Revit 2010

In case you ever have problems with the installation of Revit, the Autodesk Revit Architecture Services & Support area includes a page describing a method to achieve a clean uninstall of Revit 2010 products.

Title Block of Sheet

Here is a question that crops up now and then in different variations, on how to access the title block information of a sheet:

Question: My drawing list routine exports various sheet view information to a spreadsheet. I would like to include the name of the title block family that is associated with the view. What is the best way to find it? Do I need to loop through family instances, and do a reverse lookup?

My snooping tool freaks out whenever I select a title block family from the list of family instances, so I don't know if the host of that family instance will tie it to the specific sheet view?

Answer: If your version of RvtMgdDbg fails to display some information that you are interested in, I suggest you debug it and fix the problem, e.g. start it in the debugger and add an exception handler to the offending code.

I am confused by your statement 'name of the title block family that is associated with the view'. Do you mean sheet instead of view? In general, each sheet has a title block associated with it, and then hosts multiple views.

To see which title block is added when I add a new sheet to the model, I use a technique to track all new elements added. This technique uses the Revit API introduction labs Lab 2-1 element lister. I create a file containing a list of all elements in the BIM before and after adding the sheet and then compare them. Here is the result, in this case the list of elements created by adding a new sheet to the project:

C:\tmp\ >diff RevitElementsBeforeSheet.txt RevitElementsAfterSheet.txt
2581a2582,2595
> Id=137766; Class=ViewSheet; Category=Sheets; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a26
> Id=137767; Class=Element; Category=?; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a27
> Id=137768; Class=Element; Category=Viewports; Name=Title w Line; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a28
> Id=137769; Class=Element; Category=?; Name=A101 - Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a29
> Id=137770; Class=Element; Category=Work Plane Grid; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2a
> Id=137771; Class=SketchPlane; Category=?; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2b
> Id=137772; Class=FamilyInstance; Category=Title Blocks; Name=A0 metric; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2c
> Id=137773; Class=View; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2d
> Id=137774; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2e
> Id=137775; Class=Element; Category=Viewports; Name=Title w Line; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2f
> Id=137776; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a30
> Id=137777; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a31
> Id=137778; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a32
> Id=137779; Class=Element; Category=Schedule Graphics; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a33

If these lines are truncated in the browser view, you can copy and paste them to an editor to see the full text.

From this you can see that the new sheet has the element id 137766, and the associated title block is a FamilyInstance with id 137772.

Once the new elements have been identified, the Revit API introduction labs built-in parameter checker can be used to explore their data. In the Revit user interface, I can select the sheet via Modify > Element ID > Select by ID > 137766 > OK and then invoke the built-in parameter checker to explore its parameters.

Looking at the sheet parameters sorted by type and going through all parameters whose value is an element id, I see that there is no reference to 137772, so the sheet does not have a parameter explicitly specifying the title block by its element id, as one might have hoped.

Looking at the title block parameters yields better results, among others the family that you are asking for and the sheet number:

ELEM_FAMILY_AND_TYPE_PARAM  
  Family and Type  
  ElementId 28295   
  Title Blocks 'A0 metric'

SHEET_NUMBER                
  Sheet Number     
  String            
  A101

This means that although we have not found a pointer from the sheet to the title block, we have found information about the inverse relationship from the title block to the sheet. We can therefore use the relationship inverter algorithm to identify the title block from the sheet, if needed.

I also had an idea for another, completely different approach: I tried deleting the sheet again after it had been added and checked the resulting list of elements after that operation:

C:\tmp\ >diff 
  RevitElementsAfterSheetDelete.txt 
  RevitElementsBeforeSheet.txt

Files are identical.

Happily, as it turns out, the new list of elements is exactly the same as it was before the sheet was added. This means that the deletion of the sheet caused the associated title block to be deleted as well. This means that we can probably make use of the doc.Delete method to detect dependent elements. Using that approach, you delete the sheet inside a transaction, save the list of element ids returned by the doc.Delete method, and abort the transaction to undo the deletion operation. The list of ids will then include element ids of both the sheet and the associated title block.

I hope this resolves your issue twice over.

Title Block Modification

By the way, Ricardo Cardial raised a related question on how to modify the text labels defined in the title block, which we will partially repeat here in order to ensure that these useful ideas do not get lost:

Question: How can we change the information of the scale label shown in title blocks? When we have two different scales on the sheet, the value is 'As indicated'. I would like to change that, for instance to translate it to French or Italian.

Answer: Look at the original comment for the full answer, which consists of two parts. They can be summarised like this:

• Read the data through the built-in parameter SHEET_SCALE with the display name 'Scale'. It is a string-valued parameter and is unfortunately marked as read-only.
• Modify the family file used to define the title block of the sheet.

Model Review

We recently mentioned the subscription pack for Revit 2010. In addition to the product update itself, the subscription page for Autodesk Revit Architecture 2010 includes some new applications to complement Revit workflows to:

• Validate the accuracy of building information models against pre-determined standards.
• Import and export data between a Revit project and an external database.
• Facilitate the creation of 3D models from 2D digital photographs.

These areas are obviously of great interest for developers as well. The first of these points is addressed by the model review plug-in, which includes a small API for developers or customers to hook into to specify their own rules and standards to be checked. Matt Mason of Avatech Solutions, who is one of the original Model Review developers, now kindly wrote a summary of its functionality:

Introduction

Autodesk Revit^® Model Review is a new add-in product available to Autodesk subscription customers via the Revit 2010 Subscription Advantage Pack. Model Review provides the capability to configure and run checks against Revit projects or families and provide a report of whether the checks have passed or failed. Model Review provides 35 different kinds of checks, within the areas of:

• Modelling for Energy Analysis
• Revit Family consistency and standards
• Firm or Project-based Revit Standards
• GSA Spatial Program Validation

Here is a sample screen snapshot:

The Checking Platform

Model Review is not just a configurable set of checks provided by Autodesk – it is also a platform for developers to write their own checks and plug them in to the checking process. This could be desirable if BIM administrators want to check for issues which are not possible to check with the "out-of-the-box" Model Review checks, either because the check has not yet been implemented, or because it is too specialized to ever exist in the base product.

Creating a plug-in enables a developer who understands the Revit API to write a simple extension which leverages the Model Review platform for configuring, running, and reporting check results. These "plug-in" checks can be added to built-in checks to create the complete set of checks required by a particular firm or project.

Developers implement a few methods defining how the check should be configured, executed, reported – and optionally corrected. The check is then made available and can be run by Revit users as any other check in Model Review.

For your convenience, here is a direct link to a copy of the plug-in developer guide.

An Example

For example, one firm inquired about checking for whether a door’s Fire Rating was less than its host wall’s Fire Rating. This was made even more challenging because the Fire Rating field is text-based rather than a number, so the value might contain a string like "2 hours" instead of just numbers. Still, it is a fairly simple function to write within C# or VB.NET and the Revit API. A variation of this check is provided as a sample in the Model Review installation folder along with the developer guide.

Note: While Model Review is available for either Revit 2009 or 2010 products, the plug-in capability is only available in the 2010 version.

System Versus User Family Category

Here is a simple question and suggestion on classifying categories into built-in system versus user defined.

Question: Given an arbitrary element, how can I determine whether it belongs to a system family as opposed to a user-defined family? I thought I might look at its category, but how can I see whether that is system-defined? For example, I see that a duct has a category id of -2008000. Can I depend on the fact that this category id value is negative? Or is there any other way to determine this?

Answer: There is currently no API method to distinguish system categories from user defined ones short of creating your own hardcoded list. All built-in categories have negative values, but this includes system family types, family types, and subcategories of each, so that will not help you resolve this issue.

How could such a list be created?

Unfortunately, that would have to be done manually. This Family Category and Parameters dialogue lists all the family based categories:

If the category is a top level category and not in this list, then it is probably a system family category.

Analytical Support Tolerance

Here is an interesting issue dealing with the analytical model in Revit Structure. As we see below, the issue is not really API related, but since one symptom is the missing data obtainable through the API, it is worth an explanation.

Question: We have created two columns over a three-pile cap foundation and are trying to retrieve the support data from their analytical models:

Unfortunately, the support data of the column is available only if its centre line is exactly over the analytical model location of the pile cap foundation. Else, it is not available and the property simply returns null. The main purpose of this requirement is actually to find the link between the column and the pile cap. How can we achieve this, please?

Answer: Happily, this situation is easily resolved by modifying the analytical support tolerance. First, note that the missing support data is not an API-specific problem. If you select the column through the user interface, the Show Related Warnings button is active and the warning says that the column may not be supported.

The pile cap foundation is actually four foundations – one cap foundation and three pile foundations. Geometry for the cap foundation starts at Level 1 and goes down 900. The geometries for the three pile foundations start at -900 and go down 6900. In Revit, the default position for the Isolated Foundation analytical model is at the top of the geometry. Since this is at -900, the analytical models for the pile foundations are at that elevation.

Analytical Support is governed by the Analytical Support tolerance, shown on the Analytical Model Settings tab of the Structural Settings dialog. In the attached file, this tolerance is set at 300. So even when the column's analytical model is directly over the pile foundation's analytical model, the thickness of the cap foundation (900) is keeping the column from seeing the pile foundation's analytical model.

To overcome this obstacle, increase the tolerance from 300 to 900. Then when you move the column over the top of the pile foundation, it will see the pile foundation, and the column will consider the pile foundation as a valid support.

Although that resolves the current problem, here are two additional general hints for approaches to find the link between two elements located close to each other:

• FindReferencesByDirection.
• Geometric analysis.

The FindReferencesByDirection method to find the link between the two elements determines that the pile cap foundation is located directly underneath the second column and hence is supporting it. This can be achieved by shooting a ray straight down from a point slightly raised up from the lower endpoint of the column and using FindReferencesByDirection to discover the foundation element directly underneath. FindReferencesByDirection returns an array of elements, faces, and references found when moving through the model from a specified point in a specified direction. Its use is demonstrated by the RayTraceBounce SDK sample.

You can also determine their relationship by pure geometric analysis, e.g. using a filter to collect all the structural elements on the relevant levels and then comparing the locations of their solids' faces with each other. The AreSolidsCut method defined by the RoomsRoofs SDK sample may be helpful in this context. Geometric analysis may or may not be simpler than using FindReferencesByDirection.

Unrotate North

I spent this weekend on the Rigi Mountain together with seventy other people from the alpine club. Saturday it rained quite hard most of the day, unfortunately, but a couple of us still went on a very nice hike from Rigi Scheidegg across to and over the top of Rigi Hochflueh with a beautiful view down on the Lucerne Lake and the Rütli Meadow. In the evening, we also tested how many people can be shoehorned into a wood-heated hot tub outside in snow and rain, among other interesting pastimes. Sunday I went climbing with Angela. Considering the rain from the day before and the night and it still being quite cloudy on Sunday, we were maybe the only two crazy enough to even try it. It involved the same walk from Scheidegg to Hochflueh, then searching for the climbing area, doing the climbs, and, last but not least, getting back again safely. The climbing area is called Thedys Gärtli and is on the Hochflue slabs close to the summit, so we could all the time enjoy the same beautiful view as the day before. We were extremely pleased to be able to do two very nice climbs, among the easier ones, Männertrü (4c) and Fürlinie (5c). Although we knew when we started the latter one that we would get back rather late, we actually ended up descending the mountain in total darkness and spending most of the night trying to get back to civilisation. Or, rather, all of the night, since I missed the last train out of there.

Anyway, meanwhile, our inexorable exploration of the Revit API continues, and here is another question to address which expands on our analysis of the calculation of the azimuth or Revit elements:

Question: I am using the Element.Location property to query the X and Y coordinate values of an element. I also make use of the project location and project angle. I have a problem if the Project North has been rotated. How can I determine the 'real' X and Y coordinates of an element if the Project North has been rotated?

Answer: Ok, I see what you mean.

To dive into this a little bit deeper, I implemented a new Building Coder sample command CmdUnrotateNorth to calculate the coordinates of the original unrotated element location for you. It transforms the element location back to the original coordinates to cancel effect of rotating the project north by simply determining the project north rotation angle 'a' and applying a similar transformation to the element coordinates like this:

  Transform t = Transform.get_Rotation(
    XYZ.Zero, XYZ.BasisZ, a );

To simplify testing, I implemented a helper method GetElementLocation which defines a location point for any given element having a non-null Location property:

bool GetElementLocation(
  out XYZ p,
  Element e )
{
  p = XYZ.Zero;
  bool rc = false;
  Location loc = e.Location;
  if( null != loc )
  {
    LocationPoint lp = loc as LocationPoint;
    if( null != lp )
    {
      p = lp.Point;
      rc = true;
    }
    else
    {
      LocationCurve lc = loc as LocationCurve;

      Debug.Assert( null != lc,
        "expected location to be either point or curve" );

      p = lc.Curve.get_EndPoint( 0 );
      rc = true;
    }
  }
  return rc;
}

In the main method, I check that one single element is selected and then list its location point as returned by the API, or rather by this method. I then iterate over all project locations, print each one's the project north angle and list the element location point rotated around the origin by that angle.

I tested this by selecting an element and running the command with it in its original unrotated position, which returns:

Selected element location: (-23.64,1.64,0)
Angle between project north and true north: 0 degrees
Unrotated element location: (-23.64,1.64,0)

After applying a rotation to the project north by calling Manage > Project Location > Position > Rotate Project North > Align selected line or plane, invoking the same command again returns the following:

Selected element location: (-21.66,9.62,0)
Angle between project north and true north: 20 degrees
Unrotated element location: (-23.64,1.64,0)

As you can see, the element location returned by the API is different, but the original value can easily be obtained by applying the rotation described.

Here is the code of the entire mainline of the sample command in its Execute method:

Application app = commandData.Application;
Document doc = app.ActiveDocument;

ElementSet els = doc.Selection.Elements;

if( 1 != els.Size )
{
  message = "Please select a single element.";
}
else
{
  ElementSetIterator it = els.ForwardIterator();
  it.MoveNext();

  Element e = it.Current as Element;

  XYZ p;
  if( !GetElementLocation( out p, e ) )
  {
    message
      = "Selected element has no location defined.";

    Debug.Print( message );
  }
  else
  {
    string msg
      = "Selected element location: "
      + Util.PointString( p );

    double pna = 0;

    foreach( ProjectLocation location
      in doc.ProjectLocations )
    {
      ProjectPosition projectPosition
        = location.get_ProjectPosition( XYZ.Zero );

      pna = projectPosition.Angle;

      msg +=
        "\nAngle between project north and true north: "
        + Util.AngleString( pna );

      Transform t = Transform.get_Rotation(
        XYZ.Zero, XYZ.BasisZ, pna );

      msg +=
        "\nUnrotated element location: "
        + Util.PointString( t.OfPoint( p ) );

      Util.InfoMsg( msg );
    }
  }
}
return IExternalCommand.Result.Failed;

Here is version 1.1.0.50 of the complete Building Coder sample source code and Visual Studio solution including the new command.

DUT versus UST

After a wonderful weekend in the Swiss alps climbing the Diechterhorn, here is a follow-up explanation by Jeremy Sawicki of Autodesk on the difference between DisplayUnitType and UnitSymbolType in continuation of our last discussion on the unit suffix.

Question: What is the exact difference between DisplayUnitType and UnitSymbolType, please?

For instance, the default project unit settings on my system for a length are DUT_Millimetres and UST_None ... I wonder what exactly that means?

Also, can you suggest a way to obtain the display string representation shown in the user interface for either of these?

Answer: The simplest answer is based on the UI. In the Format dialog box, DisplayUnitType corresponds to the Units dropdown:

And UnitSymbolType corresponds to the Unit symbol dropdown:

In most cases, the DisplayUnitType determines the actual unit, for example feet vs. meters, with a different conversion factor applying to each DisplayUnitType. UnitSymbolType affects how the units are indicated on the screen, usually with a suffix. For example, square feet can use a suffix of either SF or ft² or no suffix at all. UnitSymbolType used to be called UnitSuffixType until we introduced a currency unit type, which uses prefixes in some cases, like $.

The above applies to most normal units which are displayed as a number followed by a suffix, but there are various special cases. For example, DisplayUnitType is also used to select certain kinds of units with special formatting, like Feet and fractional inches or Degrees minutes seconds.

I don't believe there is currently any API that can get the names of display unit types or unit symbol types.

Many thanks to Jeremy for this helpful clarification!