Setting up your ViewOrientation3D

Here is a contribution from Mario Guttman of

CASE,
who already made various contributions here in the past.
He says:

I have been purging my 2013 code of deprecated functions in preparation for my 2014 upgrade.
One group of statements I have needed to replace are the view creations.
They were previously using the Document.Create.NewView3D method and needed converting to the View3D.CreateIsometric with a separate ViewOrientation3D object defining the view direction.

Typically, in these kind of cases, I just search your blog for the answer.
In this case I found a few references, for example your March 04, 2013 item on

What’s New in the Revit 2013 API – View API – View Creation.
This, together with the

wikihelp entry on the View3D class,
describe the new syntax, but they don’t really explain how you would create the values.

After searching the inner reaches of my brain for some ancient math skills I figured out the following:

Assuming that your user interface has produced two angular values (in degrees):

  /// <summary>
  /// The angle in the XY plane (azimuth),
  /// typically 0 to 360.
  /// </summary>
  double angleHorizD;
 
  /// <summary>
  /// The vertical tilt (altitude),
  /// typically -90 to 90.
  /// </summary>
  double angleVertD;

Then this utility function returns a unit vector in the specified direction:

  /// <summary>
  /// Return a unit vector in the specified direction.
  /// </summary>
  /// <param name="angleHorizD">Angle in XY plane 
  /// in degrees</param>
  /// <param name="angleVertD">Vertical tilt between 
  /// -90 and +90 degrees</param>
  /// <returns>Unit vector in the specified 
  /// direction.</returns>
  private XYZ VectorFromHorizVertAngles(
    double angleHorizD,
    double angleVertD )
  {
    // Convert degreess to radians.
 
    double degToRadian = Math.PI * 2 / 360;
    double angleHorizR = angleHorizD * degToRadian;
    double angleVertR = angleVertD * degToRadian;
 
    // Return unit vector in 3D
 
    double a = Math.Cos( angleVertR );
    double b = Math.Cos( angleHorizR );
    double c = Math.Sin( angleHorizR );
    double d = Math.Sin( angleVertR );
 
    return new XYZ( a * b, a * c, d );
  }

From this it is easy to create the ViewOrientation3D object as follows:

  XYZ eye = XYZ.Zero;
 
  XYZ forward = VectorFromHorizVertAngles(
    angleHorizD, angleVertD );
 
  XYZ up = VectorFromHorizVertAngles(
    angleHorizD, angleVertD + 90 );
 
  ViewOrientation3D viewOrientation3D
    = new ViewOrientation3D( eye, up, forward );

Although it is already explained in one of your other posts, just for completeness, here is the final step is to apply the orientation to the view:

  ViewFamilyType viewFamilyType3D
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ViewFamilyType ) )
      .Cast<ViewFamilyType>()
      .FirstOrDefault<ViewFamilyType>(
        x => ViewFamily.ThreeDimensional
          == x.ViewFamily );
 
  View3D view3d = View3D.CreateIsometric(
    doc, viewFamilyType3D.Id );
 
  view3d.SetOrientation( viewOrientation3D );

I hope you find this useful.

Personally, I do indeed.

Many thanks to Mario for sharing!

Addendum

Colmag adds in
his comment below:

Thank you for sharing this info, it’s made life a whole lot easier in setting 3D view orientation.

It did take me a short while to work out the values to replicate top and bottom isometric views from each corner of the view cube, so I thought I’d share the values here for others. Looking at them listed out they are pretty obvious, but faced with a blank sheet things didn’t seem so straight forward!

• Horizontal Angles:
• Left Front = 45
• Front Right = 135
• Right Back = 225
• Back Left = 310
• Vertical Angles:
• -30 = Top
• 30 = Bottom

Many thanks to Colmag for this useful addition!

Addendum 2

K C Tang added a further simplification in
his comment below:

I found that the formula above using ( a * b, a * c, d ) to calculate the return value from VectorFromHorizVertAngles can be further simplified, because:

( a * b, a * c, d )
≡ ( a * b / a , a * c / a, d / a )
= (b, c, d/a)
= (b, c, e),

where

double e = Math.Tan( angleVertR ).

In words, the return value from VectorFromHorizVertAngles can be defined as:

• cos (horizontal angle) for X
• sin (horizontal angle) for Y
• tan (vertical angle) for Z

Many thanks to K C Tang for this simplification and explanation highlighting the basic trigonometric relationships between the angles and the vectors involved so much better than the original version!