def XformChangeBasis(initial_plane, final_plane):
    """Returns a change of basis transformation matrix or None on error
    Parameters:
      initial_plane = the initial plane
      final_plane = the final plane
    Returns:
      The 4x4 transformation matrix if successful, otherwise None
    Example:
      import rhinoscriptsyntax as rs
      import math
      objs = rs.GetObjects("Select objects to shear")
      if objs:
      cplane = rs.ViewCPlane()
      cob = rs.XformChangeBasis(rs.WorldXYPlane(), cplane)
      shear2d = rs.XformIdentity()
      shear2d[0,2] = math.tan(math.radians(45.0))
      cob_inverse = rs.XformChangeBasis(cplane, rs.WorldXYPlane())
      temp = rs.XformMultiply(shear2d, cob)
      xform = rs.XformMultiply(cob_inverse, temp)
      rs.TransformObjects( objs, xform, True )
    See Also:
      XformCPlaneToWorld
      XformWorldToCPlane
    """
    initial_plane = rhutil.coerceplane(initial_plane, True)
    final_plane = rhutil.coerceplane(final_plane, True)
    xform = Rhino.Geometry.Transform.ChangeBasis(initial_plane, final_plane)
    if not xform.IsValid: return scriptcontext.errorhandler()
    return xform

def PlaneSphereIntersection(plane, sphere_plane, sphere_radius):
    """Calculates the intersection of a plane and a sphere
    Parameters:
      plane = the plane to intersect
      sphere_plane = equitorial plane of the sphere. origin of the plane is
        the center of the sphere
      sphere_radius = radius of the sphere
    Returns:
      list of intersection results - see help
      None on error
    Example:
      import rhinoscriptsyntax as rs
      plane = rs.WorldXYPlane()
      radius = 10
      results = rs.PlaneSphereIntersection(plane, plane, radius)
      if results:
      if results[0]==0:
      rs.AddPoint(results[1])
      else:
      rs.AddCircle(results[1], results[2])
    See Also:
      IntersectPlanes
      LinePlaneIntersection
      PlanePlaneIntersection
    """
    plane = rhutil.coerceplane(plane, True)
    sphere_plane = rhutil.coerceplane(sphere_plane, True)
    sphere = Rhino.Geometry.Sphere(sphere_plane, sphere_radius)
    rc, circle = Rhino.Geometry.Intersect.Intersection.PlaneSphere(plane, sphere)
    if rc==Rhino.Geometry.Intersect.PlaneSphereIntersection.Point:
        return 0, circle.Center
    if rc==Rhino.Geometry.Intersect.PlaneSphereIntersection.Circle:
        return 1, circle.Plane, circle.Radius

def XformChangeBasis(initial_plane, final_plane):
    "Returns a change of basis transformation matrix or None on error"
    initial_plane = rhutil.coerceplane(initial_plane, True)
    final_plane = rhutil.coerceplane(final_plane, True)
    xform = Rhino.Geometry.Transform.ChangeBasis(initial_plane, final_plane)
    if not xform.IsValid: return scriptcontext.errorhandler()
    return xform

def IntersectPlanes(plane1, plane2, plane3):
    """Calculates the intersection of three planes
    Parameters:
      plane1 = the 1st plane to intersect
      plane2 = the 2nd plane to intersect
      plane3 = the 3rd plane to intersect
    Returns:
      Point3d on success
      None on error
    Example:
      import rhinoscriptsyntax as rs
      plane1 = rs.WorldXYPlane()
      plane2 = rs.WorldYZPlane()
      plane3 = rs.WorldZXPlane()
      point = rs.IntersectPlanes(plane1, plane2, plane3)
      if point: rs.AddPoint(point)
    See Also:
      LineLineIntersection
      LinePlaneIntersection
      PlanePlaneIntersection
    """
    plane1 = rhutil.coerceplane(plane1, True)
    plane2 = rhutil.coerceplane(plane2, True)
    plane3 = rhutil.coerceplane(plane3, True)
    rc, point = Rhino.Geometry.Intersect.Intersection.PlanePlanePlane(plane1, plane2, plane3)
    if rc: return point

def IntersectPlanes(plane1, plane2, plane3):
    """Calculates the intersection of three planes
    Returns:
      Point3d on success
      None on error
    """
    plane1 = rhutil.coerceplane(plane1, True)
    plane2 = rhutil.coerceplane(plane2, True)
    plane3 = rhutil.coerceplane(plane3, True)
    rc, point = Rhino.Geometry.Intersect.Intersection.PlanePlanePlane(plane1, plane2, plane3)
    if rc: return point

def PlanePlaneIntersection(plane1, plane2):
    """Calculates the intersection of two planes
    Paramters:
      plane1, plane2 = two planes
    Returns:
      two 3d points identifying the starting/ending points of the intersection
      None on error
    """
    plane1 = rhutil.coerceplane(plane1, True)
    plane2 = rhutil.coerceplane(plane2, True)
    rc, line = Rhino.Geometry.Intersect.Intersection.PlanePlane(plane1, plane2)
    if rc: return line.From, line.To

def XformRotation1(initial_plane, final_plane):
    """Returns a rotation transformation that maps initial_plane to final_plane.
    The planes should be right hand orthonormal planes.
    Returns:
      The 4x4 transformation matrix.
      None on error.
    """
    initial_plane = rhutil.coerceplane(initial_plane, True)
    final_plane = rhutil.coerceplane(final_plane, True)
    xform = Rhino.Geometry.Transform.PlaneToPlane(initial_plane, final_plane)
    if not xform.IsValid: return scriptcontext.errorhandler()
    return xform

def TextObjectPlane(object_id, plane=None):
    """Returns or modifies the plane used by a text object
    Parameters:
      object_id = the identifier of a text object
      plane[opt] = the new text object plane
    Returns:
      if a plane is not specified, the current plane if successful
      if a plane is specified, the previous plane if successful
      None if not successful, or on Error
    Example:
      import rhinoscriptsyntax as rs
      obj = rs.GetObject("Select text")
      if rs.IsText(obj):
      plane = rs.ViewCPlane("Top")
      rs.TextObjectPlane( obj, plane )
    See Also:
      AddText
      IsText
      TextObjectFont
      TextObjectHeight
      TextObjectPoint
      TextObjectStyle
      TextObjectText
    """
    annotation = rhutil.coercegeometry(object_id, True)
    if not isinstance(annotation, Rhino.Geometry.TextEntity):
        return scriptcontext.errorhandler()
    rc = annotation.Plane
    if plane:
        annotation.Plane = rhutil.coerceplane(plane, True)
        id = rhutil.coerceguid(object_id, True)
        scriptcontext.doc.Objects.Replace(id, annotation)
        scriptcontext.doc.Views.Redraw()
    return rc

def LineCylinderIntersection(line, cylinder_plane, cylinder_height, cylinder_radius):
    """Calculates the intersection of a line and a cylinder
    Parameters:
      line = the line to intersect
      cylinder_plane = base plane of the cylinder
      cylinder_height = height of the cylinder
      cylinder_radius = radius of the cylinder
    Returns:
      list of intersection points (0, 1, or 2 points)
    Example:
      import rhinoscriptsyntax as rs
      plane = rs.WorldXYPlane()
      line = (-10,0,0), (10,0,10)
      points = rs.LineCylinderIntersection(line, plane, cylinder_height=10, cylinder_radius=5)
      if points:
      for point in points: rs.AddPoint(point)
    See Also:
      LineLineIntersection
      LinePlaneIntersection
      LineSphereIntersection
    """
    line = rhutil.coerceline(line, True)
    cylinder_plane = rhutil.coerceplane(cylinder_plane, True)
    circle = Rhino.Geometry.Circle( cylinder_plane, cylinder_radius )
    if not circle.IsValid: raise ValueError("unable to create valid circle with given plane and radius")
    cyl = Rhino.Geometry.Cylinder( circle, cylinder_height )
    if not cyl.IsValid: raise ValueError("unable to create valid cylinder with given circle and height")
    rc, pt1, pt2 = Rhino.Geometry.Intersect.Intersection.LineCylinder(line, cyl)
    if rc==Rhino.Geometry.Intersect.LineCylinderIntersection.None:
        return []
    if rc==Rhino.Geometry.Intersect.LineCylinderIntersection.Single:
        return [pt1]
    return [pt1, pt2]

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 PlaneClosestPoint(plane, point, return_point=True):
    """Returns the point on a plane that is closest to a test point.
    Parameters:
      plane = The plane
      point = The 3-D point to test.
      return_point [opt] = If omitted or True, then the point on the plane
         that is closest to the test point is returned. If False, then the
         parameter of the point on the plane that is closest to the test
         point is returned.
    Returns:
      If return_point is omitted or True, then the 3-D point
      If return_point is False, then an array containing the U,V parameters
      of the point
      None if not successful, or on error.
    Example:
      import rhinoscriptsyntax as rs
      point = rs.GetPoint("Point to test")
      if point:
      plane = rs.ViewCPlane()
      if plane:
      print rs.PlaneClosestPoint(plane, point)
    See Also:
      DistanceToPlane
      EvaluatePlane
    """
    plane = rhutil.coerceplane(plane, True)
    point = rhutil.coerce3dpoint(point, True)
    if return_point:
        return plane.ClosestPoint(point)
    else:
        rc, s, t = plane.ClosestParameter(point)
        if rc: return s, t

def PlaneEquation(plane):
    """Returns the equation of a plane as a tuple of four numbers. The standard
    equation of a plane with a non-zero vector is Ax+By+Cz+D=0
    """
    plane = rhutil.coerceplane(plane, True)
    rc = plane.GetPlaneEquation()
    return rc[0], rc[1], rc[2], rc[3]

def AddPictureFrame(plane, filename, width=0.0, height=0.0, self_illumination=True, embed=False, use_alpha=False, make_mesh=False):
  """Creates a picture frame and adds it to the document.
  Parameters:
    plane = The plane in which the PictureFrame will be created.  The bottom-left corner of picture will be at plane's origin. The width will be in the plane's X axis direction, and the height will be in the plane's Y axis direction.
    filename = The path to a bitmap or image file.
    width = If both dblWidth and dblHeight = 0, then the width and height of the PictureFrame will be the width and height of the image. If dblWidth = 0 and dblHeight is > 0, or if dblWidth > 0 and dblHeight = 0, then the non-zero value is assumed to be an aspect ratio of the image's width or height, which ever one is = 0. If both dblWidth and dblHeight are > 0, then these are assumed to be the width and height of in the current unit system.
    height =  If both dblWidth and dblHeight = 0, then the width and height of the PictureFrame will be the width and height of the image. If dblWidth = 0 and dblHeight is > 0, or if dblWidth > 0 and dblHeight = 0, then the non-zero value is assumed to be an aspect ratio of the image's width or height, which ever one is = 0. If both dblWidth and dblHeight are > 0, then these are assumed to be the width and height of in the current unit system.
    self_illumination =  If True, then the image mapped to the picture frame plane always displays at full intensity and is not affected by light or shadow.
    embed = If True, then the function adds the image to Rhino's internal bitmap table, thus making the document self-contained.
    use_alpha = If False, the picture frame is created without any transparency texture.  If True, a transparency texture is created with a "mask texture" set to alpha, and an instance of the diffuse texture in the source texture slot.
    make_mesh = If True, the function will make a PictureFrame object from a mesh rather than a plane surface.
  Returns:
    object identifier on success
    None on failure
  Example:
    
  See Also:
    
  """
  plane = rhutil.coerceplane(plane, True)
  if type(filename) is not System.String or not System.IO.File.Exists(filename): raise Exception('\"{0}\" does not exist or is not a file name'.format(filename))
  rc = scriptcontext.doc.Objects.AddPictureFrame(plane, filename, make_mesh, width, height, self_illumination, embed) 
  if rc==System.Guid.Empty: raise Exception("unable to add picture frame to document")
  scriptcontext.doc.Views.Redraw()
  return rc

def XformPlanarProjection(plane):
    """Returns a transformation matrix that projects to a plane.
    Parameters
      plane = The plane to project to.
    Returns:
      The 4x4 transformation matrix.
    """
    plane = rhutil.coerceplane(plane, True)
    return Rhino.Geometry.Transform.PlanarProjection(plane)

def BoundingBox(objects, view_or_plane=None, in_world_coords=True):
    """Returns either world axis-aligned or a construction plane axis-aligned
    bounding box of an object or of several objects
    Parameters:
      objects = The identifiers of the objects
      view_or_plane[opt] = Title or id of the view that contains the
          construction plane to which the bounding box should be aligned -or-
          user defined plane. If omitted, a world axis-aligned bounding box
          will be calculated
      in_world_coords[opt] = return the bounding box as world coordinates or
          construction plane coordinates. Note, this option does not apply to
          world axis-aligned bounding boxes.
    Returns:
      Eight 3D points that define the bounding box. Points returned in counter-
      clockwise order starting with the bottom rectangle of the box.
      None on error
    """
    def __objectbbox(object, xform):
        geom = rhutil.coercegeometry(object, False)
        if not geom:
            pt = rhutil.coerce3dpoint(object, True)
            return Rhino.Geometry.BoundingBox(pt,pt)
        if xform: return geom.GetBoundingBox(xform)
        return geom.GetBoundingBox(True)

    xform = None
    plane = rhutil.coerceplane(view_or_plane)
    if plane is None and view_or_plane:
        view = view_or_plane
        modelviews = scriptcontext.doc.Views.GetStandardRhinoViews()
        for item in modelviews:
            viewport = item.MainViewport
            if type(view) is str and viewport.Name==view:
                plane = viewport.ConstructionPlane()
                break
            elif type(view) is System.Guid and viewport.Id==view:
                plane = viewport.ConstructionPlane()
                break
        if plane is None: return scriptcontext.errorhandler()
    if plane:
        xform = Rhino.Geometry.Transform.ChangeBasis(Rhino.Geometry.Plane.WorldXY, plane)
    bbox = Rhino.Geometry.BoundingBox.Empty
    if type(objects) is list or type(objects) is tuple:
        for object in objects:
            objectbbox = __objectbbox(object, xform)
            bbox = Rhino.Geometry.BoundingBox.Union(bbox,objectbbox)
    else:
        objectbbox = __objectbbox(objects, xform)
        bbox = Rhino.Geometry.BoundingBox.Union(bbox,objectbbox)
    if not bbox.IsValid: return scriptcontext.errorhandler()

    corners = list(bbox.GetCorners())
    if in_world_coords and plane is not None:
        plane_to_world = Rhino.Geometry.Transform.ChangeBasis(plane, Rhino.Geometry.Plane.WorldXY)
        for pt in corners: pt.Transform(plane_to_world)
    return corners

def PlaneTransform(plane, xform):
    """Transforms a plane
    Parameters:
      plane = Plane to transform
      xform = Transformation to apply
    """
    plane = rhutil.coerceplane(plane, True)
    xform = rhutil.coercexform(xform, True)
    rc = Rhino.Geometry.Plane(plane)
    if rc.Transform(xform): return rc

def EvaluatePlane(plane, parameter):
    """Evaluates a plane at a U,V parameter
    Parameters:
      plane = the plane to evaluate
      parameter = list of two numbers defining the U,V parameter to evaluate
    Returns:
      Point3d on success
    """
    plane = rhutil.coerceplane(plane, True)
    return plane.PointAt(parameter[0], parameter[1])

def PlaneSphereIntersection(plane, sphere_plane, sphere_radius):
    """Calculates the intersection of a plane and a sphere
    Parameters:
      plane = the plane to intersect
      sphere_plane = equitorial plane of the sphere. origin of the plane is
        the center of the sphere
      sphere_radius = radius of the sphere
    Returns:
      list of intersection results - see help
      None on error
    """
    plane = rhutil.coerceplane(plane, True)
    sphere_plane = rhutil.coerceplane(sphere_plane, True)
    sphere = Rhino.Geometry.Sphere(sphere_plane, sphere_radius)
    rc, circle = Rhino.Geometry.Intersect.Intersection.PlaneSphere(plane, sphere)
    if rc==Rhino.Geometry.Intersect.PlaneSphereIntersection.Point:
        return 0, circle.Center
    if rc==Rhino.Geometry.Intersect.PlaneSphereIntersection.Circle:
        return 1, circle.Plane, circle.Radius

def PlaneTransform(plane, xform):
    """Transforms a plane
    Parameters:
      plane = OnPlane or On3dmConstructionPlane
      xform = 
    """
    plane = rhutil.coerceplane(plane, True)
    xform = rhutil.coercexform(xform, True)
    rc = Rhino.Geometry.Plane(plane)
    if rc.Transform(xform): return rc
    return scriptcontext.errorhandler()

def XformCPlaneToWorld(point, plane):
    """Transform point from construction plane coordinates to world coordinates
    Parameters:
      point = A 3D point in construction plane coordinates.
      plane = The construction plane
    Returns:
      A 3D point in world coordinates
    """
    point = rhutil.coerce3dpoint(point, True)
    plane = rhutil.coerceplane(plane, True)
    return plane.Origin + point.X*plane.XAxis + point.Y*plane.YAxis + point.Z*plane.ZAxis