/// <summary>
/// Subtracts the specified vector from this vector and returns the result.
/// </summary>
/// <param name="source">The vector to subtract from this vector.</param>
/// <returns>The vector equal to the difference between the two vectors.</returns>
/// <remarks>The subtracted vector is obtained by subtracting each coordinate of the specified vector from
/// the corresponding coordinate of this vector.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public XYZ Subtract(XYZ source)
{
NullCheck(source, "source");
return(new XYZ(X - source.X, Y - source.Y, Z - source.Z));
}
/// <summary>
/// Determines whether this vector is parallel with the given vector.
/// </summary>
/// <param name="source">The given vector.</param>
/// <returns>True if parallel, false otherwise.</returns>
/// <remarks>Two vectors are parellel if there exists a constant C where a = Cb.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public bool ParallelWith(XYZ source)
{
NullCheck(source, "source");
return((DotProduct(this) * source).IsAlmostEqualTo(DotProduct(source) * this));
}
/// <summary>
/// Projects the given vector on this vector.
/// </summary>
/// <param name="source">The vector to project onto this vector.</param>
/// <returns>The projected vector.</returns>
/// <remarks>The projected vector will be in the same direction as this vector. The magnitude of the vector
/// will be the magnitude of the given vector in this direction.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public XYZ Project(XYZ source)
{
NullCheck(source, "source");
return((DotProduct(source) / source.GetLength()) * Normalize());
}
/// <summary>
/// Determines whether this vector and the specified vector are the same within the tolerance (1.0e-09).
/// (Might not be how Revit does it).
/// </summary>
/// <param name="source">The vector to compare with this vector.</param>
/// <returns>True if the vectors are the same; otherwise, false.</returns>
/// <remarks>This routine uses Revit's default tolerance to compare two vectors to see if they are almost
/// equivalent. Because the tolerance is small enough this can also be used to compare two
/// points.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public bool IsAlmostEqualTo(XYZ source)
{
return(IsAlmostEqualTo(source, 1.0E-09));
}
/// <summary>
/// The dot product of this vector and the specified vector.
/// </summary>
/// <param name="source">The vector to multiply with this vector.</param>
/// <returns>The real number equal to the dot product.</returns>
/// <remarks>The dot product is the sum of the respective coordinates of the two vectors:
/// Vx*Wx + Vy*Wy + Vz*Wz. Also known as scalar product or inner product.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public double DotProduct(XYZ source)
{
NullCheck(source, "source");
return((X * source.X) + (Y * source.Y) + (Z * source.Z));
}
/// <summary>
/// Returns the distance from this point to the specified point.
/// </summary>
/// <param name="source">The specified point.</param>
/// <returns>The real number equal to the distance between the two points.</returns>
/// <remarks>The distance between the two points is equal to the length of the vector that joins the two
/// points.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public double DistanceTo(XYZ source)
{
NullCheck(source, "source");
return(Math.Sqrt(Math.Pow(source.X - X, 2) + Math.Pow(source.Y - Y, 2) + Math.Pow(source.Z - Z, 2)));
}
/// <summary>
/// Returns the angle between this vector and the specified vector.
/// </summary>
/// <param name="source">The specified vector.</param>
/// <returns>The real number between 0 and PI equal to the angle between the two vectors in
/// radians.</returns>
/// <remarks>The angle between the two vectors is measured in the plane spanned by them.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>"
public double AngleTo(XYZ source)
{
NullCheck(source, "source");
return(Math.Acos(DotProduct(source) / (GetLength() * source.GetLength())));
}
/// <summary>
/// Adds the specified vector to this vector and returns the result.
/// </summary>
/// <param name="source">The vector to add to this vector.</param>
/// <returns>The vector equal to the sum of the two vectors.</returns>
/// <remarks>The added vector is obtained by adding each coordinate of the specified vector to the
/// corresponding coordinate of this vector.</remarks>
/// <exception cref="ArgumentNullException">Thrown when source is a null reference.</exception>
public XYZ Add(XYZ source)
{
NullCheck(source, "source");
return(new XYZ(X + source.X, Y + source.Y, Z + source.Z));
}
