def PlaneFromFrame(origin, x_axis, y_axis):
    """Construct a plane from a point, and two vectors in the plane.
    Parameters:
      origin = A 3D point identifying the origin of the plane.
      x_axis = A non-zero 3D vector in the plane that determines the X axis
               direction.
      y_axis = A non-zero 3D vector not parallel to x_axis that is used
               to determine the Y axis direction. Note, y_axis does not
               have to be perpendicular to x_axis.
    Returns:
      The plane if successful. 
    Example:
      import rhinoscriptsyntax as rs
      origin = rs.GetPoint("CPlane origin")
      if origin:
      xaxis = (1,0,0)
      yaxis = (0,0,1)
      plane = rs.PlaneFromFrame( origin, xaxis, yaxis )
      rs.ViewCPlane(None, plane)
    See Also:
      MovePlane
      PlaneFromNormal
      PlaneFromPoints
      RotatePlane
    """
    origin = rhutil.coerce3dpoint(origin, True)
    x_axis = rhutil.coerce3dvector(x_axis, True)
    y_axis = rhutil.coerce3dvector(y_axis, True)
    return Rhino.Geometry.Plane(origin, x_axis, y_axis)

def VectorAngle(vector1, vector2):
    """Returns the angle, in degrees, between two 3-D vectors
    Parameters:
      vector1 = List of 3 numbers, Point3d, or Vector3d.  The first 3-D vector.
      vector2 = List of 3 numbers, Point3d, or Vector3d.  The second 3-D vector.
    Returns:
      The angle in degrees if successfull, otherwise None
    Example:
      import rhinoscriptsyntax as rs
      s0 = rs.GetObject("Surface 0", rs.filter.surface)
      s1 = rs.GetObject("Surface 1", rs.filter.surface)
      du0 = rs.SurfaceDomain(s0, 0)
      dv0 = rs.SurfaceDomain(s0, 1)
      du1 = rs.SurfaceDomain(s1, 0)
      dv1 = rs.SurfaceDomain(s1, 1)
      n0 = rs.SurfaceNormal(s0, (du0[0], dv0[0]))
      n1 = rs.SurfaceNormal(s1, (du1[0], dv1[0]))
      print rs.VectorAngle(n0, n1)
      print rs.VectorAngle(n0, rs.VectorReverse(n1))
    See Also:
      Angle
      Angle2
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    vector1 = Rhino.Geometry.Vector3d(vector1.X, vector1.Y, vector1.Z)
    vector2 = Rhino.Geometry.Vector3d(vector2.X, vector2.Y, vector2.Z)
    if not vector1.Unitize() or not vector2.Unitize():
        raise ValueError("unable to unitize vector")
    dot = vector1 * vector2
    dot = rhutil.clamp(-1,1,dot)
    radians = math.acos(dot)
    return math.degrees(radians)

def XformShear(plane, x, y, z):
    """Returns a shear transformation matrix
    Parameters:
      plane = plane[0] is the fixed point
      x,y,z = each axis scale factor
    Returns:
      The 4x4 transformation matrix on success
    Example:
      import rhinoscriptsyntax as rs
      objects = rs.GetObjects("Select objects to shear")
      if objects:
      cplane = rs.ViewCPlane()
      xform = rs.XformShear(cplane, (1,1,0), (-1,1,0), (0,0,1))
      rs.TransformObjects(objects, xform, True)
    See Also:
      XformMirror
      XformPlanarProjection
      XformRotation
      XformScale
      XformTranslation
    """
    plane = rhutil.coerceplane(plane, True)
    x = rhutil.coerce3dvector(x, True)
    y = rhutil.coerce3dvector(y, True)
    z = rhutil.coerce3dvector(z, True)
    return Rhino.Geometry.Transform.Shear(plane,x,y,z)

def PlaneFromNormal(origin, normal, xaxis=None):
    """Creates a plane from an origin point and a normal direction vector.
    Parameters:
      origin = A 3D point identifying the origin of the plane.
      normal = A 3D vector identifying the normal direction of the plane.
      xaxis[opt] = optional vector defining the plane's x-axis
    Returns:
      The plane if successful.
    Example:
      import rhinoscriptsyntax as rs
      origin = rs.GetPoint("CPlane origin")
      if origin:
      direction = rs.GetPoint("CPlane direction")
      if direction:
      normal = direction - origin
      normal = rs.VectorUnitize(normal)
      rs.ViewCPlane( None, rs.PlaneFromNormal(origin, normal) )
    See Also:
      MovePlane
      PlaneFromFrame
      PlaneFromPoints
      RotatePlane
    """
    origin = rhutil.coerce3dpoint(origin, True)
    normal = rhutil.coerce3dvector(normal, True)
    rc = Rhino.Geometry.Plane(origin, normal)
    if xaxis:
        xaxis = rhutil.coerce3dvector(xaxis, True)
        xaxis = Rhino.Geometry.Vector3d(xaxis)#prevent original xaxis parameter from being unitized too
        xaxis.Unitize()
        yaxis = Rhino.Geometry.Vector3d.CrossProduct(rc.Normal, xaxis)
        rc = Rhino.Geometry.Plane(origin, xaxis, yaxis)
    return rc

def IsVectorPerpendicularTo(vector1, vector2):
    """Compares two vectors to see if they are perpendicular
    Parameters:
      vector1, vector2 = the vectors to compare
    Returns:
      True if vectors are perpendicular, otherwise False
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return vector1.IsPerpendicularTo(vector2)

def VectorCrossProduct(vector1, vector2):
    """Calculates the cross product of two 3D vectors
    Parameters:
      vector1, vector2 = the vectors to perform cross product on
    Returns:
      the resulting vector if successful
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return Rhino.Geometry.Vector3d.CrossProduct( vector1, vector2 )

def VectorDotProduct(vector1, vector2):
    """Calculates the dot product of two 3D vectors
    Parameters:
      vector1, vector2 = the vectors to perform the dot product on
    Returns:
      the resulting dot product if successful
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return vector1*vector2

def VectorAdd(vector1, vector2):
    """Adds two 3D vectors
    Parameters:
      vector1, vector2 = the vectors to add
    Returns:
      the resulting 3D vector if successful
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return vector1+vector2

def VectorSubtract(vector1, vector2):
    """Subtracts two 3D vectors
    Parameters:
      vector1 = the vector to subtract from
      vector2 = the vector to subtract
    Returns:
      the resulting 3D vector
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return vector1-vector2

def IsVectorParallelTo(vector1, vector2):
    """Compares two vectors to see if they are parallel
    Parameters:
      vector1, vector2 = the vectors to compare
    Returns:
      -1 = the vectors are anti-parallel
      0 = the vectors are not parallel
      1 = the vectors are parallel
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return vector1.IsParallelTo(vector2)

def VectorAngle(vector1, vector2):
    "Returns the angle, in degrees, between two 3-D vectors"
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    vector1 = Rhino.Geometry.Vector3d(vector1.X, vector1.Y, vector1.Z)
    vector2 = Rhino.Geometry.Vector3d(vector2.X, vector2.Y, vector2.Z)
    if not vector1.Unitize() or not vector2.Unitize():
        raise ValueError("unable to unitize vector")
    dot = vector1 * vector2
    dot = rhutil.clamp(-1,1,dot)
    radians = math.acos(dot)
    return math.degrees(radians)

def VectorCompare(vector1, vector2):
    """Compares two 3D vectors
    Parameters:
      vector1, vector2 = the vectors to compare
    Returns:
      -1 if vector1 is less than vector2
      0 if vector1 is equal to vector2
      1 if vector1 is greater than vector2
    """
    vector1 = rhutil.coerce3dvector(vector1, True)
    vector2 = rhutil.coerce3dvector(vector2, True)
    return vector1.CompareTo(vector2)

def XformShear(plane, x, y, z):
    """Returns a shear transformation matrix
    Parameters:
      plane = plane[0] is the fixed point
      x,y,z = each axis scale factor
    Returns:
      The 4x4 transformation matrix on success
    """
    plane = rhutil.coerceplane(plane, True)
    x = rhutil.coerce3dvector(x, True)
    y = rhutil.coerce3dvector(y, True)
    z = rhutil.coerce3dvector(z, True)
    return Rhino.Geometry.Transform.Shear(plane,x,y,z)

def VectorRotate(vector, angle_degrees, axis):
    """Rotates a 3D vector
    Parameters:
      vector = the vector to rotate
      angle_degrees = rotation angle
      axis = axis of rotation
    Returns:
      rotated vector on success
    """
    vector = rhutil.coerce3dvector(vector, True)
    axis = rhutil.coerce3dvector(axis, True)
    angle_radians = Rhino.RhinoMath.ToRadians(angle_degrees)
    rc = Rhino.Geometry.Vector3d(vector.X, vector.Y, vector.Z)
    if rc.Rotate(angle_radians, axis): return rc

def PlaneFromFrame(origin, x_axis, y_axis):
    """Construct a plane from a point, and two vectors in the plane.
    Parameters:
      origin = A 3D point identifying the origin of the plane.
      x_axis = A non-zero 3D vector in the plane that determines the X axis
               direction.
      y_axis = A non-zero 3D vector not parallel to x_axis that is used
               to determine the Y axis direction. Note, y_axis does not
               have to be perpendicular to x_axis.
    Returns:
      The plane if successful. 
    """
    origin = rhutil.coerce3dpoint(origin, True)
    x_axis = rhutil.coerce3dvector(x_axis, True)
    y_axis = rhutil.coerce3dvector(y_axis, True)
    return Rhino.Geometry.Plane(origin, x_axis, y_axis)

def XformRotation3( start_direction, end_direction, center_point ):
    """Calculate the minimal transformation that rotates start_direction to
    end_direction while fixing center_point
    Parameters:
      start_direction, end_direction = 3d vectors
      center_point = the rotation center
    Returns:
      The 4x4 transformation matrix.
      None on error.
    """
    start = rhutil.coerce3dvector(start_direction, True)
    end = rhutil.coerce3dvector(end_direction, True)
    center = rhutil.coerce3dpoint(center_point, True)
    xform = Rhino.Geometry.Transform.Rotation(start, end, center)
    if not xform.IsValid: return scriptcontext.errorhandler()
    return xform

def ProjectPointToMesh(points, mesh_ids, direction):
    """Projects one or more points onto one or more meshes
    Parameters:
      points = one or more 3D points
      mesh_ids = identifiers of one or more meshes
      direction = direction vector to project the points
    Returns:
     list of projected points on success
    Example:
      import rhinoscriptsyntax as rs
      mesh = rs.GetObject("Select mesh to project onto", rs.filter.mesh)
      objects = rs.GetObjects("Select points to project", rs.filter.point)
      points = [rs.PointCoordinates(obj) for obj in objects]
      # project down...
      results = rs.ProjectPointToMesh(points, mesh, (0,0,-1))
      rs.AddPoints( results )
    See Also:
      ProjectCurveToMesh
      ProjectCurveToSurface
      ProjectPointToSurface
    """
    pts = rhutil.coerce3dpointlist(points, False)
    if pts is None:
        pts = [rhutil.coerce3dpoint(points, True)]
    direction = rhutil.coerce3dvector(direction, True)
    id = rhutil.coerceguid(mesh_ids, False)
    if id: mesh_ids = [id]
    meshes = [rhutil.coercemesh(id, True) for id in mesh_ids]
    tolerance = scriptcontext.doc.ModelAbsoluteTolerance
    rc = Rhino.Geometry.Intersect.Intersection.ProjectPointsToMeshes(meshes, pts, direction, tolerance)
    return rc

def ProjectPointToSurface(points, surface_ids, direction):
    """Projects one or more points onto one or more surfaces or polysurfaces
    Parameters:
      points = one or more 3D points
      surface_ids = identifiers of one or more surfaces/polysurfaces
      direction = direction vector to project the points
    Returns:
     list of projected points on success
    Example:
      import rhinoscriptsyntax as rs
      surface = rs.GetObject("Select surface to project onto", rs.filter.surface)
      objects = rs.GetObjects("Select points to project", rs.filter.point)
      points = [rs.PointCoordinates(obj) for obj in objects]
      results = rs.ProjectPointToSurface(points, surface, (0,0,-1))
      rs.AddPoints(results)
    See Also:
      ProjectCurveToMesh
      ProjectCurveToSurface
      ProjectPointToMesh
    """
    pts = rhutil.coerce3dpointlist(points)
    if pts is None:
        pts = [rhutil.coerce3dpoint(points, True)]
    direction = rhutil.coerce3dvector(direction, True)
    id = rhutil.coerceguid(surface_ids, False)
    if id: surface_ids = [id]
    breps = [rhutil.coercebrep(id, True) for id in surface_ids]
    tolerance = scriptcontext.doc.ModelAbsoluteTolerance
    return Rhino.Geometry.Intersect.Intersection.ProjectPointsToBreps(breps, pts, direction, tolerance)

def LightDirection(object_id, direction=None):
    """Returns or changes the direction of a light object
    Parameters:
      object_id = the light object's identifier
      direction[opt] = the light's new direction
    Returns:
      if direction is not specified, the current direction
      if direction is specified, the previous direction
    Example:
      import rhinoscriptsyntax as rs
      id = rs.GetObject("Select a light", rs.filter.light)
      if id: rs.AddPoint( rs.LightDirection(id) )
    See Also:
      IsLight
      LightLocation
    """
    light = __coercelight(object_id, True)
    rc = light.Direction
    if direction:
        direction = rhutil.coerce3dvector(direction, True)
        if direction!=rc:
            light.Direction = direction
            id = rhutil.coerceguid(object_id, True)
            if not scriptcontext.doc.Lights.Modify(id, light):
                return scriptcontext.errorhandler()
            scriptcontext.doc.Views.Redraw()
    return rc

def IsVectorZero(vector):
    """Verifies that a vector is zero, or tiny. The X,Y,Z elements are equal to 0.0
    Parameters:
      vector - the vector to check
    Returns:
      True if the vector is zero, otherwise False
    """
    vector = rhutil.coerce3dvector(vector, True)
    return vector.IsZero