RayTraceBounce Pool Table

In spite of yesterday's promise to stop, here is yet one more last minute Christmas present from Harry Matttison of the Revit API development team. In Harry's own words: "Here is a modification to make the ray shooting SDK example RayTraceBounce a bit more fun ... it works and can amuse a 6 year old, if nothing else."

Harry's sample uses the ray tracing capabilities of the FindReferencesByDirection method to simulate a pool table. The model defines the table, six pockets, and a cue. The cue can be positioned in any way you like. Once positioned, you launch the RaytraceBouncePool command to calculate the walls that the ball will encounter if leaving the cue in a straight line and the reflections off them until it hits a pocket. The number of total reflections required is counted and reported. Here is a shot with four reflections:

Here is another one with just two:

The command makes use of a couple of handy utility methods:

• Get3DView returns the view named "{3D}" in the current document.
• DeleteLines deletes the lines from the previous run.
• MakeLine creates a model line with the given start point, end point, and line style.

Here is the source code of the entire external command and its utility methods, which Harry placed in the namespace RayTraceBounce:

public class RaytraceBouncePool : IExternalCommand
{
  // have a line style "bounce" created in the 
  // document before running this
 
  /// <summary>
  /// Maximum number of bounces to calculate.
  /// </summary>
  const int _max_bounces = 100;
 
  /// <summary>
  /// Message box caption.
  /// </summary>
  const string _caption = "RayTraceBounce Pool Table";
 
  ExternalCommandData cdata;
  Application app;
  Document doc;
  Face face = null;
  Reference rClosest = null;
  View3D view = null;
  static double epsilon = 0.00000001;
  int LineCount = 0;
  int RayCount = 0;
 
  public IExternalCommand.Result Execute( 
    ExternalCommandData commandData, 
    ref string message, 
    ElementSet elements )
  {
    cdata = commandData;
    app = commandData.Application;
    doc = app.ActiveDocument;
    Get3DView();
    DeleteLines();
 
    // find the cue
 
    XYZ direction = null;
    XYZ startpt = null;
 
    List<Autodesk.Revit.Element> list 
      = new List<Autodesk.Revit.Element>();
 
    Filter filter = app.Create.Filter
      .NewTypeFilter( typeof( FamilyInstance ) );
 
    int num = app.ActiveDocument.get_Elements( 
      filter, list );
 
    foreach( Autodesk.Revit.Element e in list )
    {
      if( e.Name == "cue" )
      {
        LocationCurve lc = e.Location 
          as LocationCurve;
 
        direction = lc.Curve.ComputeDerivatives( 
          0, true ).BasisX;
 
        startpt = lc.Curve.get_EndPoint( 1 );
 
        break;
      }
    }
    if( null == view )
    {
      MessageBox.Show( "A default 3D view (named {3D}) "
        + " must exist before running this command",
        _caption );
    }
    else
    {
      for( int ctr = 1; ctr <= _max_bounces; ++ctr )
      {
        ReferenceArray references 
          = doc.FindReferencesByDirection( 
            startpt, direction, view );
 
        rClosest = null;
        FindClosestReference( references );
 
        if( rClosest == null )
        {
          MessageBox.Show( "Ray " + ctr + " aborted. "
            + "No closest face reference found.",
            _caption );
 
          return IExternalCommand.Result.Succeeded;
        }
        else
        {
          XYZ endpt = new XYZ( 
            rClosest.GlobalPoint.X, 
            rClosest.GlobalPoint.Y, 
            rClosest.GlobalPoint.Z );
 
          if( startpt.AlmostEqual( endpt ) )
          {
            MessageBox.Show( 
              "Start and end points are equal. Ray " 
              + ctr + " aborted\n" 
              + startpt.X + ", " 
              + startpt.Y + ", " 
              + startpt.Z,
              _caption );
 
            break;
          }
          else
          {
            MakeLine( startpt, endpt, direction, "bounce" );
            RayCount = RayCount + 1;
            face = rClosest.GeometryObject as Face;
            if( rClosest.Element.Category.Name == "Doors" )
            {
              MessageBox.Show( "You sank the ball with " 
                + ctr + " shots.", _caption );
 
              return IExternalCommand.Result.Succeeded;
            }
            UV endptUV = rClosest.UVPoint;
 
            // face normal where ray hits
 
            XYZ faceNormal = face.ComputeDerivatives( 
              endptUV ).BasisZ;
 
            // transformation to get it in terms of 
            // document coordinates instead of the 
            // parent symbol
 
            faceNormal = rClosest.Transform.OfVector( 
              faceNormal );
 
            // http://www.fvastro.org/presentations/ray_tracing.htm
 
            XYZ directionMirrored = direction 
              - 2 * direction.Dot( faceNormal ) * faceNormal;
 
            // get ready to shoot the next ray
 
            direction = directionMirrored; 
 
            startpt = endpt;
          }
        }
      }
    }
    return IExternalCommand.Result.Succeeded;
  }
 
  /// <summary>
  /// Find closest reference.
  /// </summary>
  /// <param name="references">Input array of references</param>
  /// <returns></returns>
  public Reference FindClosestReference( 
    ReferenceArray references )
  {
    double face_prox = Double.PositiveInfinity;
    double edge_prox = Double.PositiveInfinity;
 
    foreach( Reference r in references )
    {
      if( r.Element.Category.Name != "Generic Models" )
      {
        face = null;
        face = r.GeometryObject as Face;
        Edge edge = null;
        edge = r.GeometryObject as Edge;
        if( face != null )
        {
          // when startpoint is on a surface, should 
          // FindReferencesByDirection find that surface?
 
          if( Math.Abs( r.ProximityParameter ) < face_prox 
            && r.ProximityParameter > epsilon ) 
          {
            rClosest = r;
            face_prox = Math.Abs( r.ProximityParameter );
          }
        }
        if( edge != null )
        {
          // when startpoint is on a surface, should 
          // FindReferencesByDirection find that surface?
 
          if( Math.Abs( r.ProximityParameter ) < edge_prox 
            && r.ProximityParameter > epsilon ) 
          {
            edge_prox = Math.Abs( r.ProximityParameter );
          }
        }
      }
    }
 
    // stop bouncing if there is an edge at least 
    // as close as the neareast face - there is no 
    // single angle of reflection for a ray 
    // striking a line
 
    if( edge_prox <= face_prox )
    {
      rClosest = null;
    }
    return rClosest;
  }
 
  /// <summary>
  /// Create a model line with the given start, end point, and line style.
  /// </summary>
  /// <param name="sp">Start point</param>
  /// <param name="ep">End point</param>
  /// <param name="direction">Sketch plane normal vector</param>
  /// <param name="style">Line style name</param>
  public void MakeLine( 
    XYZ sp, 
    XYZ ep, 
    XYZ direction, 
    string style )
  {
    LineCount = LineCount + 1;
 
    Line line = app.Create.NewLineBound( sp, ep );
 
    Plane geometryPlane = app.Create.NewPlane( 
      direction, sp );
 
    Document doc = app.ActiveDocument;
 
    SketchPlane skplane = doc.Create.NewSketchPlane( 
      geometryPlane );
 
    ModelCurve mcurve = doc.Create.NewModelCurve( 
      line, skplane );
 
    ElementArray lsArr = mcurve.LineStyles;
 
    foreach( Autodesk.Revit.Element e in lsArr )
    {
      if( e.Name == style )
      {
        mcurve.LineStyle = e;
        break;
      }
    }
  }
 
  /// <summary>
  /// Return the view named "{3D}" in the current document.
  /// </summary>
  public void Get3DView()
  {
    List<Autodesk.Revit.Element> list 
      = new List<Autodesk.Revit.Element>();
 
    Filter filter = app.Create.Filter.NewTypeFilter( 
      typeof( View3D ) );
 
    Int64 num = app.ActiveDocument.get_Elements( 
      filter, list );
 
    foreach( Autodesk.Revit.Element v in list )
    {
      if( v.Name == "{3D}" )
      {
        view = v as View3D;
        break;
      }
    }
  }
 
  /// <summary>
  /// Delete the lines from the previous run.
  /// </summary>
  public void DeleteLines()
  {
    List<Autodesk.Revit.Element> list 
      = new List<Autodesk.Revit.Element>();
 
    Filter filter = app.Create.Filter.NewTypeFilter( 
      typeof( CurveElement ), true );
 
    Int64 num = app.ActiveDocument.get_Elements( 
      filter, list );
 
    foreach( Autodesk.Revit.Element e in list )
    {
      ModelCurve mc = e as ModelCurve;
      if( mc != null )
      {
        if( mc.LineStyle.Name == "bounce"
          || mc.LineStyle.Name == "normal" )
        {
          app.ActiveDocument.Delete( e );
        }
      }
    }
  }
}

I integrated this into the standard RayTraceBounce SDK sample code by adding a second external command implementation class named RaytraceBouncePool to the existing project, and the following lines to my RvtSamples.txt file that I use to load all the SDK samples:

Geometry
RayTraceBounce Pool Table
Simulate a pool table.
LargeImage: 
Image: 
C:\...\SDK\Samples\RaytraceBounce\RayTraceBounce.dll
RayTraceBounce.RaytraceBouncePool

Here is the source file RaytraceBouncePool.cs and the sample project PoolTable.rvt defining the pool table and cue for downloading. I placed the sample project into the RaytraceBounce subdirectory of the SDK Samples folder, and the source file into the CS subdirectory below it.

I hope this helps further understanding of the possibilities of the Revit API and the FindReferencesByDirection method, and provides a bit of fun as well.

Many thanks to Harry for this nice sample!

Once again, and this time for good, a Very Merry Christmas and a Happy New Year to you all!

Addenda

Harry added some notes on this later:

It's fine to publish it, but I will feel bad if anyone considers an API example like this a Christmas gift   :-)   I'd feel bad because I don't think it is a very good present – sort of like getting underwear or socks as a gift. Not exactly a new iPod or Wii. But that is no reason not to post it and I hope others enjoy it. After all, underwear and socks are useful and necessary.

By the way, this is a lot more fun if you add doc.Save() at the beginning and then after each call to MakeLine so that the view updates after each bounce.

Anthony '8-Ball' Hauck noted that the message displayed should actually read "You sank the ball with 5 banks."

Comments

[Marcin Klocek]

Dear Jeremy,

I am pretty new to ReviT API and have a following issue: I am batch creating a number ( big number ) of family types - actually instances of different type each, but they are all surfaces, not solids. So after every element is created, Revit displays a warning, which requires answer OK or CANCEL and this kills my idea of batch creating. How to make API answer always OK to such window ? I have already a function which handles this dialog box from Revit, but I can only ignore it using dialogBoxData.OverrideResult(1) function. And this of course prevents the element from being created .... prevents. I am working in Revit VSTA and IDE. My code is
below:
sing System;
using System.Windows.Forms;
using Autodesk;
using Autodesk.Revit;
using Autodesk.Revit.Elements;
using Autodesk.Revit.Structural.Enums;
using Autodesk.Revit.Symbols;
using Autodesk.Revit.Geometry;
using Autodesk.Revit.Events;

namespace V_family_test
{
[System.AddIn.AddIn("ThisApplication", Version = "1.0", Publisher = "", Description = "")]
public partial class ThisApplication
{
private void Module_Startup(object sender, EventArgs e)
{
this.OnDialogBox += new DialogBoxEventHandler(ThisApplication_OnDialogBox);
}

private void Module_Shutdown(object sender, EventArgs e)
{
this.OnDialogBox -= new DialogBoxEventHandler(ThisApplication_OnDialogBox);
}

void ThisApplication_OnDialogBox(DialogBoxData dialogBoxData)
{
dialogBoxData.OverrideResult(3);
}

#region VSTA generated code
private void InternalStartup()
{
this.Startup += new System.EventHandler(Module_Startup);
this.Shutdown += new System.EventHandler(Module_Shutdown);
}
#endregion

public void Create_V_test()
{

String fileName = @"C:\Test_Macro\WesternFins_Module.rfa";
Document document = this.ActiveDocument;

document.BeginTransaction();

Family family = null;
if (!document.LoadFamily(fileName, out family))
{
throw new Exception("Unable to load" + fileName);
}

document.EndTransaction();

FamilySymbolSetIterator symbolItor = family.Symbols.ForwardIterator();
while (symbolItor.MoveNext())
{
FamilySymbol symbol = symbolItor.Current as FamilySymbol;

document.BeginTransaction();
XYZ location = this.Create.NewXYZ(0.0, 0.0, 0.0);
FamilyInstance instance = document.Create.NewFamilyInstance(location, symbol, StructuralType.NonStructural);
document.EndTransaction();
}
}
}
}

[Jeremy Tammik]

Dear Marcin,

Look at the Revit API documentation on the DialogBoxShowingEventArgs.OverrideResult method.

Any non-zero result will close the message box, not just the number 1.

You can return any standard Windows message box ID, such as IDOK and IDCANCEL, and all custom text buttons have custom IDs with incremental values starting at 1001, so they are all non-zero.

Find the ID corresponding to the button you want clicked and use that instead of the number 1.

If nothing else helps, you can also use the technique described in

http://thebuildingcoder.typepad.com/blog/2009/10/dismiss-dialogue-using-windows-api.html

Cheers, Jeremy.