def AddSpotLight(origin, radius, apex_point):
    """Adds a new spot light object to the document
    Parameters:
      origin = 3d origin point of the light
      radius = radius of the cone
      apex_point = 3d apex point of the light
    Returns:
      identifier of the new object
    Example:
      import rhinoscriptsyntax as rs
      radius = 5.0
      origin = rs.GetPoint("Base of cone")
      if origin:
      apex = rs.GetPoint("End of cone", origin)
      if apex: rs.AddSpotLight(origin, radius, apex)
    See Also:
      IsSpotLight
      SpotLightHardness
      SpotLightShadowIntensity
    """
    origin = rhutil.coerce3dpoint(origin, True)
    apex_point = rhutil.coerce3dpoint(apex_point, True)
    if radius<0: radius=1.0
    light = Rhino.Geometry.Light()
    light.LightStyle = Rhino.Geometry.LightStyle.WorldSpot
    light.Location = apex_point
    light.Direction = origin-apex_point
    light.SpotAngleRadians = math.atan(radius / (light.Direction.Length))
    light.HotSpot = 0.50
    index = scriptcontext.doc.Lights.Add(light)
    if index<0: raise Exception("unable to add light to LightTable")
    rc = scriptcontext.doc.Lights[index].Id
    scriptcontext.doc.Views.Redraw()
    return rc

def WindowPick(corner1, corner2, view=None, select=False, in_window=True):
    """Picks objects using either a window or crossing selection
    Parameters:
      corner1, corner2 = corners of selection window
      view[opt] = view to perform the selection in
      select[opt] = select picked objects
      in_window[opt] = if False, then a crossing window selection is performed
    Returns:
      list of object ids on success
    Example:
      import rhinoscriptsyntax as  rs
      rs.WindowPick((0,0,0), (0,0,0),  None, True)
    See Also:
      
    """
    viewport = __viewhelper(view).MainViewport
    screen1 = Rhino.Geometry.Point2d(rhutil.coerce3dpoint(corner1, True))
    screen2 = Rhino.Geometry.Point2d(rhutil.coerce3dpoint(corner2, True))
    xf = viewport.GetTransform(Rhino.DocObjects.CoordinateSystem.World, Rhino.DocObjects.CoordinateSystem.Screen)
    screen1.Transform(xf)
    screen2.Transform(xf)
    objects = None
    filter = Rhino.DocObjects.ObjectType.AnyObject
    if in_window:
        objects = scriptcontext.doc.Objects.FindByWindowRegion(viewport, screen1, screen2, True, filter)
    else:
        objects = scriptcontext.doc.Objects.FindByCrossingWindowRegion(viewport, screen1, screen2, True, filter)
    if objects:
        rc = []
        for rhobj in objects:
            rc.append(rhobj.Id)
            if select: rhobj.Select(True)
        if select: scriptcontext.doc.Views.Redraw()
        return rc

def GetAngle(point=None, reference_point=None, default_angle_degrees=0, message=None):
    """Pause for user input of an angle
    Parameters:
      point(opt) = starting, or base point
      reference_point(opt) = if specified, the reference angle is calculated
        from it and the base point
      default_angle_degrees(opt) = a default angle value specified
      message(opt) = a prompt to display
    Returns:
      angle in degree if successful, None on error
    Example:
      import rhinoscriptsyntax as rs
      point = rs.GetPoint("Base point")
      if point:
      reference = rs.GetPoint("Reference point", point)
      if reference:
      angle = rs.GetAngle(point, reference)
      if angle!=None: print "Angle:", angle
    See Also:
      GetDistance
    """
    point = rhutil.coerce3dpoint(point)
    if not point: point = Rhino.Geometry.Point3d.Unset
    reference_point = rhutil.coerce3dpoint(reference_point)
    if not reference_point: reference_point = Rhino.Geometry.Point3d.Unset
    default_angle = math.radians(default_angle_degrees)
    rc, angle = Rhino.Input.RhinoGet.GetAngle(message, point, reference_point, default_angle)
    if rc==Rhino.Commands.Result.Success: return math.degrees(angle)

def AddRectangularLight(origin, width_point, height_point):
    """Adds a new rectangular light object to the document
    Parameters:
      origin = 3d origin point of the light
      width_point = 3d width and direction point of the light
      height_point = 3d height and direction point of the light
    Returns:
      identifier of the new object if successful
    """
    origin = rhutil.coerce3dpoint(origin, True)
    ptx = rhutil.coerce3dpoint(width_point, True)
    pty = rhutil.coerce3dpoint(height_point, True)
    length = pty-origin
    width = ptx-origin
    normal = Rhino.Geometry.Vector3d.CrossProduct(width, length)
    normal.Unitize()
    light = Rhino.Geometry.Light()
    light.LightStyle = Rhino.Geometry.LightStyle.WorldRectangular
    light.Location = origin
    light.Width = width
    light.Length = length
    light.Direction = normal
    index = scriptcontext.doc.Lights.Add(light)
    if index<0: raise Exception("unable to add light to LightTable")
    rc = scriptcontext.doc.Lights[index].Id
    scriptcontext.doc.Views.Redraw()
    return rc

def AddAlignedDimension(start_point, end_point, point_on_dimension_line, style=None):
    """Adds an aligned dimension object to the document. An aligned dimension
    is a linear dimension lined up with two points
    Parameters:
      start_point: first point of dimension
      end_point: second point of dimension
      point_on_dimension_line: location point of dimension line
      style[opt]: name of dimension style
    Returns:
      identifier of new dimension on success
      None on error
    """
    start = rhutil.coerce3dpoint(start_point, True)
    end = rhutil.coerce3dpoint(end_point, True)
    onpoint = rhutil.coerce3dpoint(point_on_dimension_line, True)
    plane = Rhino.Geometry.Plane(start, end, onpoint)
    success, s, t = plane.ClosestParameter(start)
    start = Rhino.Geometry.Point2d(s,t)
    success, s, t = plane.ClosestParameter(end)
    end = Rhino.Geometry.Point2d(s,t)
    success, s, t = plane.ClosestParameter(onpoint)
    onpoint = Rhino.Geometry.Point2d(s,t)
    ldim = Rhino.Geometry.LinearDimension(plane, start, end, onpoint)
    if not ldim: return scriptcontext.errorhandler()
    ldim.Aligned = True
    rc = scriptcontext.doc.Objects.AddLinearDimension(ldim)
    if rc==System.Guid.Empty: raise Exception("unable to add dimension to document")
    scriptcontext.doc.Views.Redraw()
    return rc

def XformScale(scale, point=None):
    """Creates a scale transformation
    Parameters:
      scale = single number, list of 3 numbers, Point3d, or Vector3d
      point[opt] = center of scale. If omitted, world origin is used
    Returns:
      The 4x4 transformation matrix on success
      None on error
    Example:
      import rhinoscriptsyntax as rs
      objs = rs.GetObjects("Select objects to scale")
      if objs:
      xform = rs.XformScale( (3.0,1.0,1.0) )
      rs.TransformObjects( objs, xform, True)
    See Also:
      XformMirror
      XformPlanarProjection
      XformRotation
      XformShear
      XformTranslation
    """
    factor = rhutil.coerce3dpoint(scale)
    if factor is None:
        if type(scale) is int or type(scale) is float:
            factor = (scale,scale,scale)
        if factor is None: return scriptcontext.errorhandler()
    if point: point = rhutil.coerce3dpoint(point, True)
    else: point = Rhino.Geometry.Point3d.Origin
    plane = Rhino.Geometry.Plane(point, Rhino.Geometry.Vector3d.ZAxis);
    xf = Rhino.Geometry.Transform.Scale(plane, factor[0], factor[1], factor[2])
    return xf

def ShearObjects(object_ids, origin, reference_point, angle_degrees, copy=False):
    """Shears one or more objects
    Parameters:
      object_ids: The identifiers objects to shear
      origin, reference_point: origin/reference point of the shear transformation
    Returns:
      List of identifiers of the sheared objects if successful
    """
    origin = rhutil.coerce3dpoint(origin, True)
    reference_point = rhutil.coerce3dpoint(reference_point, True)
    if (origin-reference_point).IsTiny(): return None
    plane = scriptcontext.doc.Views.ActiveView.MainViewport.ConstructionPlane()
    frame = Rhino.Geometry.Plane(plane)
    frame.Origin = origin
    frame.ZAxis = plane.Normal
    yaxis = reference_point-origin
    yaxis.Unitize()
    frame.YAxis = yaxis
    xaxis = Rhino.Geometry.Vector3d.CrossProduct(frame.ZAxis, frame.YAxis)
    xaxis.Unitize()
    frame.XAxis = xaxis

    world_plane = Rhino.Geometry.Plane.WorldXY
    cob = Rhino.Geometry.Transform.ChangeBasis(world_plane, frame)
    shear2d = Rhino.Geometry.Transform.Identity
    shear2d[0,1] = math.tan(math.radians(angle_degrees))
    cobinv = Rhino.Geometry.Transform.ChangeBasis(frame, world_plane)
    xf = cobinv * shear2d * cob
    rc = TransformObjects(object_ids, xf, copy)
    return rc

def PointCompare(point1, point2, tolerance=None):
    """Compares two 3D points
    Parameters:
      point1, point2 = the points to compare
      tolerance [opt] = tolerance to use for comparison. If omitted,
        Rhino's internal zero tolerance is used
    Returns:
      True or False
    Example:
      import rhinoscriptsyntax as rs
      point1 = (1,1,1)
      point2 = (2,2,2)
      print rs.PointCompare(point1, point2)
    See Also:
      PointAdd
      PointDivide
      PointScale
      PointSubtract
      PointTransform
    """
    point1 = rhutil.coerce3dpoint(point1, True)
    point2 = rhutil.coerce3dpoint(point2, True)
    if tolerance is None: tolerance = Rhino.RhinoMath.ZeroTolerance
    vector = point2-point1
    return vector.IsTiny(tolerance)

def AddDirectionalLight(start_point, end_point):
    """Adds a new directional light object to the document
    Parameters:
      start_point: starting point of the light
      end_point: ending point and direction of the light
    Returns:
      identifier of the new object if successful
    Example:
      import rhinoscriptsyntax as rs
      end = rs.GetPoint("End of light vector direction")
      if end:
      start = rs.GetPoint("Start of light vector direction", end)
      if start: rs.AddDirectionalLight( start, end )
    See Also:
      IsDirectionalLight
    """
    start = rhutil.coerce3dpoint(start_point, True)
    end = rhutil.coerce3dpoint(end_point, True)
    light = Rhino.Geometry.Light()
    light.LightStyle = Rhino.Geometry.LightStyle.WorldDirectional
    light.Location = start
    light.Direction = end-start
    index = scriptcontext.doc.Lights.Add(light)
    if index<0: raise Exception("unable to add light to LightTable")
    rc = scriptcontext.doc.Lights[index].Id
    scriptcontext.doc.Views.Redraw()
    return rc

def VectorCreate(to_point, from_point):
    """Creates a vector from two 3D points
    Parameters:
      to_point, from_point = the points defining the vector
    Returns:
      the resulting vector if successful
    """
    to_point = rhutil.coerce3dpoint(to_point, True)
    from_point = rhutil.coerce3dpoint(from_point, True)
    return to_point-from_point

def PointAdd(point1, point2):
    """Adds a 3D point or a 3D vector to a 3D point
    Parameters:
      point1, point2 = the points to add
    Returns:
      the resulting 3D point if successful
    """
    point1 = rhutil.coerce3dpoint(point1, True)
    point2 = rhutil.coerce3dpoint(point2, True)
    return point1+point2

def PointSubtract(point1, point2):
    """Subtracts a 3D point or a 3D vector from a 3D point
    Parameters:
      point1, point2 = the points to subtract
    Returns:
      the resulting 3D point if successful
    """
    point1 = rhutil.coerce3dpoint(point1, True)
    point2 = rhutil.coerce3dpoint(point2, True)
    v = point1-point2
    return Rhino.Geometry.Point3d(v)

def PlaneFromPoints(origin, x, y):
    """Creates a plane from three non-colinear points
    Parameters:
      origin = origin point of the plane
      x, y = points on the plane's x and y axes
    """
    origin = rhutil.coerce3dpoint(origin, True)
    x = rhutil.coerce3dpoint(x, True)
    y = rhutil.coerce3dpoint(y, True)
    plane = Rhino.Geometry.Plane(origin, x, y)
    if plane.IsValid: return plane

def PointCompare(point1, point2, tolerance=None):
    """Compares two 3D points
    Parameters:
      point1, point2 = the points to compare
      tolerance [opt] = tolerance to use for comparison. If omitted,
        Rhino's internal zero tolerance is used
    Returns:
      True or False
    """
    point1 = rhutil.coerce3dpoint(point1, True)
    point2 = rhutil.coerce3dpoint(point2, True)
    if tolerance is None: tolerance = Rhino.RhinoMath.ZeroTolerance
    vector = point2-point1
    return vector.IsTiny(tolerance)

def AddLinearDimension(start_point, end_point, point_on_dimension_line):
    """Adds a linear dimension to the document
    Returns:
      identifier of the new object on success
      None on error
    """
    start = rhutil.coerce3dpoint(start_point, True)
    end = rhutil.coerce3dpoint(end_point, True)
    onpoint = rhutil.coerce3dpoint(point_on_dimension_line, True)
    ldim = Rhino.Geometry.LinearDimension.FromPoints(start, end, onpoint)
    if not ldim: return scriptcontext.errorhandler()
    rc = scriptcontext.doc.Objects.AddLinearDimension(ldim)
    if rc==System.Guid.Empty: raise Exception("unable to add dimension to document")
    scriptcontext.doc.Views.Redraw()
    return rc

def PointArrayClosestPoint(points, test_point):
    """Finds the point in a list of 3D points that is closest to a test point
    Parameters:
      points = list of points
      test_point = the point to compare against
    Returns:
      index of the element in the point list that is closest to the test point
    Example:
      import rhinoscriptsyntax as rs
      cloud= rs.GetObject("Select point cloud")
      if cloud:
      point = rs.GetPoint("Point to test")
      if point:
      cloud = rs.PointCloudPoints(cloud)
      index = rs.PointArrayClosestPoint(cloud, point)
      if index is not None:
      point_id = rs.AddPoint(cloud[index])
      rs.SelectObject( point_id )
    See Also:
      CurveClosestPoint
      SurfaceClosestPoint
    """
    points = rhutil.coerce3dpointlist(points, True)
    test_point = rhutil.coerce3dpoint(test_point, True)
    index = Rhino.Collections.Point3dList.ClosestIndexInList(points, test_point)
    if index>=0: return index

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