RhinoPy · API Reference

Applicationapp

AddAlias (alias, macro) → bool

Add new command alias to Rhino. Command aliases can be added manually via Rhino's Options → Aliases tab.

Parameters

aliasstrName of new command alias. Cannot match command names or existing aliases.

macrostrThe macro to run when the alias is executed.

Returns

bool — True/False indicating success

Example

import rhinoscriptsyntax as rs
rs.AddAlias("OriginLine", "!_Line 0,0,0")

Command (commandString, echo=True) → bool

Runs a Rhino command script. All Rhino commands can be used. Run one command per call — never combine multiple commands in a single call.

Parameters

commandStringstrA Rhino command including any arguments

echoboolIf True, displays command on commandline optional

Returns

bool — True if command executed successfully

Example

import rhinoscriptsyntax as rs
# CORRECT: one command per call
rs.Command("_Line 0,0,0 5,5,0")
rs.Command("_SelLast")

# WRONG: do not combine commands
# rs.Command("_Line _SelLast _Invert")  ← NEVER do this

EnableRedraw (enable=True) → bool

Enables/disables screen redrawing. Disable before loops that add many objects — huge performance gain. Always re-enable afterwards.

Parameters

enableboolTrue to enable, False to disable redraw optional

Returns

bool — previous state

Example

import rhinoscriptsyntax as rs
rs.EnableRedraw(False)         # disable for speed
for i in range(1000):
    rs.AddPoint([i, 0, 0])
rs.EnableRedraw(True)          # always re-enable

Ortho / Osnap / Planar (enable=None) → bool

Toggle Rhino modeling aids. Returns current state if enable omitted, otherwise sets state and returns previous.

Example

import rhinoscriptsyntax as rs
if not rs.Ortho(): rs.Ortho(True)
if not rs.Osnap(): rs.Osnap(True)
if not rs.Planar(): rs.Planar(True)

OsnapMode (mode=None) → number

Returns or sets the object snap mode bitmask. Combine modes by adding values.

Mode Values

0NoneNo snapping

2NearNear snap

32CenterCenter snap

2048MidpointMidpoint snap

8192IntersectionIntersection snap

131072EndEndpoint snap

2097152TangentTangent snap

Example

import rhinoscriptsyntax as rs
# Enable only End snap
rs.OsnapMode(131072)
# Add End to current modes
mode = rs.OsnapMode()
rs.OsnapMode(mode + 131072)

ExeVersion / ExePlatform / BuildDate () → str / date

Query Rhino executable and SDK info.

Example

import rhinoscriptsyntax as rs
print("Rhino Version:",  rs.ExeVersion())
print("Platform:",       rs.ExePlatform())   # 1 = 64-bit
print("Build Date:",     rs.BuildDate())
print("SDK Version:",    rs.SdkVersion())
print("Install Folder:", rs.InstallFolder())

Prompt / CommandHistory (message=None) / () → none / str

Set command prompt text or retrieve command history log.

Example

import rhinoscriptsyntax as rs
rs.Prompt("Select a curve to measure")
history = rs.CommandHistory()
print(history[-200:])   # last 200 chars

Sleep (milliseconds) → none

Suspends execution for specified milliseconds. Use for animations or waiting for Rhino to catch up.

Example

import rhinoscriptsyntax as rs
for i in range(10):
    rs.AddPoint([i, 0, 0])
    rs.Sleep(100)   # pause 0.1s between each point

Curvecurve

AddLine (start, end) → guid

Creates a line from two 3D points. Returns the identifier (GUID) of the new object, or None on failure.

Parameters

startpoint3D start point [x, y, z]

endpoint3D end point [x, y, z]

Example

import rhinoscriptsyntax as rs
line_id = rs.AddLine([0,0,0], [10,5,0])
length  = rs.CurveLength(line_id)
print("Length:", length)

AddPolyline (points) → guid

Creates a polyline curve from a list of points. Minimum 2 points.

Parameters

pointslistList of 3D points [[x,y,z], ...]

Example

import rhinoscriptsyntax as rs
pts = [[0,0,0],[5,0,0],[5,5,0],[0,5,0],[0,0,0]]
poly_id = rs.AddPolyline(pts)

AddCurve / AddInterpCurve / AddNurbsCurve (points, degree=3) → guid

AddCurve — control-point curve through or near points.
AddInterpCurve — interpolated (passes through all points).
AddNurbsCurve — full NURBS with optional knots and weights.

Parameters

pointslistList of 3D control/interpolation points

degreeintCurve degree. 1=polyline, 3=cubic, 5=quintic optional

Example

import rhinoscriptsyntax as rs
import math

pts = [[i, math.sin(i), 0] for i in range(20)]
crv1 = rs.AddCurve(pts, 3)        # smooth cubic
crv2 = rs.AddInterpCurve(pts, 3)  # interpolated
crv3 = rs.AddCurve(pts, 5)        # degree-5

AddArc / AddCircle / AddEllipse various parameters → guid

Primitive conic curve constructors.

Example

import rhinoscriptsyntax as rs
import math

# Circle at origin, radius 5
circle = rs.AddCircle([0,0,0], 5)

# Arc: plane, radius, start angle, end angle (degrees)
plane = rs.WorldXYPlane()
arc   = rs.AddArc(plane, 3, 90)   # 90-degree arc

# Ellipse: plane, radiusX, radiusY
ellipse = rs.AddEllipse(plane, 5, 3)

CurveLength (curve_id, segment_index=-1, sub_domain=None) → float

Returns the length of a curve object. Optionally specify a parameter sub-domain to get partial length.

Parameters

curve_idguidIdentifier of the curve

sub_domain[t0,t1]Curve parameter interval for partial length optional

Example

import rhinoscriptsyntax as rs
crv = rs.GetObject("Select a curve", rs.filter.curve)
if crv:
    length = rs.CurveLength(crv)
    domain = rs.CurveDomain(crv)
    half   = rs.CurveLength(crv, sub_domain=[domain[0], (domain[0]+domain[1])/2])
    print(f"Total: {length:.2f}, Half: {half:.2f}")

CurveDomain / CurveEndPoint / CurveStartPoint / CurveTangent (curve_id, ...) → various

Query curve geometry properties.

Example

import rhinoscriptsyntax as rs
crv = rs.GetObject("Curve", rs.filter.curve)
domain = rs.CurveDomain(crv)      # [t_start, t_end]
start  = rs.CurveStartPoint(crv)   # 3D point
end    = rs.CurveEndPoint(crv)     # 3D point
tmid   = (domain[0] + domain[1]) / 2
tang   = rs.CurveTangent(crv, tmid) # tangent vector at midpoint

DivideCurve / DivideCurveLength (curve_id, segments) / (curve_id, length) → list of points

DivideCurve — divide into N equal segments by parameter.
DivideCurveLength — divide by arc length (more evenly spaced in 3D).

Example

import rhinoscriptsyntax as rs
crv = rs.GetObject("Curve", rs.filter.curve)
pts = rs.DivideCurve(crv, 20)         # 20 segments, 21 points
pts_eq = rs.DivideCurveLength(crv, 1.0) # every 1 unit of length
for pt in pts: rs.AddPoint(pt)

EvaluateCurve (curve_id, t) → point3d

Evaluates a curve at a parameter value, returning the 3D world coordinate.

Example

import rhinoscriptsyntax as rs
crv    = rs.GetObject("Curve", rs.filter.curve)
domain = rs.CurveDomain(crv)
tmid   = (domain[0] + domain[1]) / 2
midpt  = rs.EvaluateCurve(crv, tmid)
rs.AddPoint(midpt)

CurvePoints / CurveDegree / CurveKnots / CurveWeights (curve_id) → various

Access NURBS curve data: control points, degree, knot vector, weights.

Example

import rhinoscriptsyntax as rs
crv     = rs.GetObject("NURBS Curve", rs.filter.curve)
degree  = rs.CurveDegree(crv)     # e.g. 3
pts     = rs.CurvePoints(crv)     # control points
knots   = rs.CurveKnots(crv)      # knot vector list
weights = rs.CurveWeights(crv)    # weight per control pt
print(f"Degree {degree}, {len(pts)} control points")

IsCurve / IsCurveClosed (object_id) → bool

Test if an object is a curve, and whether that curve is closed (start=end).

Example

import rhinoscriptsyntax as rs
obj = rs.GetObject("Select object")
if rs.IsCurve(obj):
    closed = rs.IsCurveClosed(obj)
    print("Closed:", closed)

Surfacesurface

AddPlaneSurface / AddSphere / AddLoftSrf various → guid

Create primitive and lofted surfaces.

Example

import rhinoscriptsyntax as rs
# Flat planar surface: plane, [width, height]
plane = rs.WorldXYPlane()
srf1  = rs.AddPlaneSurface(plane, [10,10], [10,10])

# Sphere: center, radius
srf2  = rs.AddSphere([0,0,0], 5)

# Loft through list of curves
crv1  = rs.AddCircle(rs.PlaneFromNormal([0,0,0],[0,0,1]), 3)
crv2  = rs.AddCircle(rs.PlaneFromNormal([0,0,5],[0,0,1]), 5)
loft  = rs.AddLoftSrf([crv1, crv2])

SurfaceDomain / EvaluateSurface / SurfaceFrame (srf_id, direction/uv_pt) → various

Core surface evaluation. SurfaceDomain gives the UV parameter range. EvaluateSurface returns 3D point at [u,v]. SurfaceFrame returns the full moving frame (origin, tangents, normal).

Example

import rhinoscriptsyntax as rs
srf = rs.GetObject("Surface", rs.filter.surface)

udom = rs.SurfaceDomain(srf, 0)   # U direction [min, max]
vdom = rs.SurfaceDomain(srf, 1)   # V direction [min, max]

# Evaluate at UV parameter
u = (udom[0] + udom[1]) / 2
v = (vdom[0] + vdom[1]) / 2
pt     = rs.EvaluateSurface(srf, u, v)
frame  = rs.SurfaceFrame(srf, [u, v])  # plane at (u,v)
normal = rs.SurfaceNormal(srf, [u, v]) # normal vector
rs.AddPoint(pt)

SurfaceClosestPoint (surface_id, test_point) → [u, v]

Returns the UV parameters of the closest point on a surface to a given 3D test point.

Example

import rhinoscriptsyntax as rs
srf = rs.GetObject("Surface", rs.filter.surface)
pt  = rs.GetPoint("Pick a point")
uv  = rs.SurfaceClosestPoint(srf, pt)   # [u, v]
closest = rs.EvaluateSurface(srf, uv[0], uv[1])
rs.AddLine(pt, closest)                # visualise distance

SurfacePoints / SurfacePointCount / SurfaceKnots (surface_id) → various

Access NURBS surface data: control point grid, counts (U×V), knot vectors.

Example

import rhinoscriptsyntax as rs
srf   = rs.GetObject("NURBS Surface", rs.filter.surface)
count = rs.SurfacePointCount(srf)   # [Nu, Nv]
pts   = rs.SurfacePoints(srf)       # list of control points
print(f"Grid: {count[0]} x {count[1]} = {len(pts)} points")

AddInterpCrvOnSrf / ExtractIsoCurve various → guid

AddInterpCrvOnSrf — interpolated curve on a surface (geodesic-like).
ExtractIsoCurve — extract an isocurve at a parameter value.

Example

import rhinoscriptsyntax as rs
srf  = rs.GetObject("Surface", rs.filter.surface)
udom = rs.SurfaceDomain(srf, 0)

# Extract U isocurve at midpoint
umid = (udom[0] + udom[1]) / 2
iso  = rs.ExtractIsoCurve(srf, umid, 0)  # 0=U, 1=V

Geometrygeometry

Distance / Angle (pt1, pt2) / (pt1, pt2, pt3) → float

Distance — 3D Euclidean distance between two points.
Angle — angle in degrees between two vectors or at a point.

Example

import rhinoscriptsyntax as rs
p1 = [0, 0, 0]
p2 = [3, 4, 0]
d  = rs.Distance(p1, p2)        # → 5.0
p3 = [3, 0, 0]
ang= rs.Angle(p1, p2, p3)       # angle at p1 between p2 and p3

BrepClosestPoint (object_id, point) → [pt, normal, face_uv, …]

Returns the closest point on a Brep (solid/surface) to a test point. Returns a tuple: [closest_point, normal, face_uv, component_type, component_index].

Example

import rhinoscriptsyntax as rs
brep = rs.GetObject("Brep", rs.filter.surface)
pt   = rs.GetPoint("Test point")
result = rs.BrepClosestPoint(brep, pt)
closest, normal = result[0], result[1]
rs.AddLine(pt, closest)
rs.AddLine(closest, rs.VectorAdd(closest, rs.VectorScale(normal,1)))

Objectobject

DeleteObject / DeleteObjects (object_id) / (object_ids) → bool / int

Delete one or more objects from the document.

Example

import rhinoscriptsyntax as rs
tmp_pts = []
for i in range(5):
    tmp_pts.append(rs.AddPoint([i, 0, 0]))
# … do work …
rs.DeleteObjects(tmp_pts)   # clean up all at once

ObjectName / ObjectColor / ObjectLayer (object_id, value=None) → str / color

Get or set object attributes. If value omitted, returns current. If value given, sets and returns previous.

Example

import rhinoscriptsyntax as rs
obj = rs.GetObject("Object")
rs.ObjectName(obj, "MyBeam")
rs.ObjectColor(obj, (255, 0, 0))   # red
rs.ObjectLayer(obj, "Structure")

ScaleObject / MoveObject / RotateObject various → guid

Transform objects. These create new objects or modify in place depending on copy flag.

Example

import rhinoscriptsyntax as rs
obj = rs.GetObject("Object")
# Scale: origin, [sx, sy, sz], copy=False
rs.ScaleObject(obj, [0,0,0], [2,2,2])

# Move: translation vector
rs.MoveObject(obj, [10,0,0])

# Rotate around Z axis 45°
rs.RotateObject(obj, [0,0,0], 45, [0,0,1])

ObjectsByType (geometry_type, select=False, state=0) → list of guid

Returns all objects of a given geometry type. Type filter values match rs.filter constants.

Common filter values

rs.filter.point1Point objects

rs.filter.curve4Curves

rs.filter.surface8Surfaces / Breps

rs.filter.mesh32Mesh objects

Example

import rhinoscriptsyntax as rs
curves = rs.ObjectsByType(rs.filter.curve)
print(f"Found {len(curves)} curves")
for c in curves:
    print(rs.CurveLength(c))

Point / Vectormath

AddPoint / AddPoints (point) / (points) → guid / list

Adds a 3D point object (visible dot) to the document.

Example

import rhinoscriptsyntax as rs
import math
pts = [[i, math.sin(i * 0.5), 0] for i in range(30)]
rs.AddPoints(pts)   # batch add — faster

Vector Math Functions VectorAdd / VectorSubtract / VectorScale / VectorUnitize / VectorLength / VectorCrossProduct / VectorDotProduct / VectorRotate → vector/float

Full set of 3D vector math operations. Vectors are plain [x, y, z] lists.

Example

import rhinoscriptsyntax as rs
a = [1, 0, 0]
b = [0, 1, 0]

v_sum   = rs.VectorAdd(a, b)         # [1,1,0]
v_diff  = rs.VectorSubtract(a, b)    # [1,-1,0]
v_scale = rs.VectorScale(a, 5)       # [5,0,0]
v_unit  = rs.VectorUnitize(v_sum)    # unit vector
length  = rs.VectorLength(v_sum)     # √2 ≈ 1.414
cross   = rs.VectorCrossProduct(a, b) # [0,0,1] = Z-axis
dot     = rs.VectorDotProduct(a, b)   # 0 (perpendicular)
rot_v   = rs.VectorRotate(a, 90, [0,0,1])  # rotate 90° around Z

print(f"Cross product: {cross}")
print(f"Parallel? {rs.IsVectorParallelTo(a, [2,0,0])}")

PointAdd / PointSubtract (point, vector) → point3d

Move a point by a vector (point arithmetic).

Example

import rhinoscriptsyntax as rs
pt  = [0, 0, 0]
vec = [0, 0, 5]
pt2 = rs.PointAdd(pt, vec)      # [0, 0, 5]
pt3 = rs.PointSubtract(pt2, vec) # back to [0, 0, 0]

Meshmesh

AddMesh / MeshVertices / MeshFaceVertices various → guid / list

AddMesh — create mesh from vertex list and face indices. MeshVertices — get vertex coordinates. MeshFaceVertices — get vertex indices per face.

Example — Create a simple quad mesh

import rhinoscriptsyntax as rs
verts  = [[0,0,0],[1,0,0],[1,1,0],[0,1,0]]
# Face: 4 vertex indices (quad) = [v0, v1, v2, v3]
faces  = [(0,1,2,3)]
mesh   = rs.AddMesh(verts, faces)

# Read back
v_out = rs.MeshVertices(mesh)
f_out = rs.MeshFaceVertices(mesh)
print(f"{len(v_out)} verts, {len(f_out)} faces")

Layerlayer

AddLayer / ObjectLayer / LayerNames / CurrentLayer various → str / bool

Full layer management. Layers use double-colon syntax for nesting: "Parent::Child".

Example

import rhinoscriptsyntax as rs
# Create layers
rs.AddLayer("Structure")
rs.AddLayer("Structure::Beams")   # nested layer
rs.AddLayer("Structure::Columns")

# Set layer color
rs.LayerColor("Structure::Beams", (255, 100, 0))

# Move object to layer
obj = rs.GetObject("Select beam")
rs.ObjectLayer(obj, "Structure::Beams")

# List all layers
layers = rs.LayerNames()
for l in layers: print(l)

Selectionselect

GetObject / GetObjects / GetPoint (message, filter, preselect, ...) → guid / list / point

Interactive selection prompts. GetObject picks one object; GetObjects picks multiple; GetPoint picks a 3D coordinate.

Filter constants (rs.filter.*)

rs.filter.point1Points

rs.filter.curve4Curves

rs.filter.surface8Surfaces/Breps

rs.filter.polysurface16Polysurfaces

rs.filter.mesh32Meshes

rs.filter.annotation512Annotations

Example

import rhinoscriptsyntax as rs

# Select one curve
crv = rs.GetObject("Select a curve", rs.filter.curve)
if not crv: print("Cancelled"); exit()

# Select multiple surfaces
srfs = rs.GetObjects("Select surfaces", rs.filter.surface)

# Pick a point with snap
pt = rs.GetPoint("Pick base point")

# Get surface specifically
s = rs.GetSurfaceObject("Select surface")
# Returns (surface_id, uv_param, point) tuple

SelectObject / UnselectObject / SelectAllObjects (object_id) → bool

Programmatically select/deselect objects in the viewport.

Example

import rhinoscriptsyntax as rs
curves = rs.ObjectsByType(rs.filter.curve)
for c in curves: rs.SelectObject(c)

User InterfaceUI

GetString / GetNumber / GetInteger / GetBoolean (message, default, options) → str / float / int / bool

Simple command-line input prompts. Returns None if user cancels.

Example

import rhinoscriptsyntax as rs

name   = rs.GetString("Project name", "MyProject")
count  = rs.GetInteger("How many copies", 5, 1, 100)
scale  = rs.GetNumber("Scale factor", 1.0)
mirror = rs.GetBoolean("Mirror?", ["Mirror","No","Yes"], [True])

if name is not None:
    print(f"Creating {count} copies of '{name}'")

MessageBox / ListBox / EditBox / StringBox various → str / int

Popup dialog boxes for user interaction.

Example

import rhinoscriptsyntax as rs

# Simple message
rs.MessageBox("Done! Script completed successfully.")

# List choice
items  = ["Concrete", "Steel", "Timber", "Composite"]
choice = rs.ListBox(items, "Material type:", "Select Material")

# Multi-line text input
text = rs.EditBox("Enter your notes:", "Notes", "Script Notes")

print(f"Selected: {choice}")

GetColor (color=(0,0,0)) → (r,g,b)

Displays Rhino's color picker dialog. Returns selected color as (r, g, b) tuple or None if cancelled.

Example

import rhinoscriptsyntax as rs
obj   = rs.GetObject("Object to color")
color = rs.GetColor(rs.ObjectColor(obj))
if color:
    rs.ObjectColor(obj, color)

Utilityutil

UnitAbsoluteTolerance / UnitAngleTolerance (in_host_units=False) → float

Returns the document's absolute tolerance setting. Crucial for robust geometry checks.

Example

import rhinoscriptsyntax as rs
tol = rs.UnitAbsoluteTolerance()  # typically 0.001
crv = rs.GetObject("Curve", rs.filter.curve)
length = rs.CurveLength(crv)
if length < tol:
    print("Curve is effectively zero-length")
elif length < tol * 10:
    print("Curve is very short")

ZoomExtents / ZoomSelected / Redraw (view=None) / () → none

Control viewport display.

Example

import rhinoscriptsyntax as rs
rs.EnableRedraw(False)
# ... batch operations ...
rs.EnableRedraw(True)
rs.ZoomExtents()   # fit all in view
rs.Redraw()        # force refresh

Transformationxform

XformTranslation / XformRotation / XformScale various → 4×4 matrix

Build transformation matrices. Use with TransformObject for custom transforms.

Example

import rhinoscriptsyntax as rs
obj   = rs.GetObject("Object")
xform = rs.XformTranslation([5,0,0])   # move +5 in X
rs.TransformObject(obj, xform)

# Combine transforms (rotation then translate)
rot   = rs.XformRotation2(45, [0,0,1], [0,0,0])
trans = rs.XformTranslation([10,0,0])
combined = rs.XformMultiply(trans, rot)
rs.TransformObject(obj, combined, copy=True)

Viewview

ViewNames / CurrentView / ViewDisplayMode various → str / list

Query and control viewport settings.

Example

import rhinoscriptsyntax as rs
views = rs.ViewNames()      # ["Top","Front","Right","Perspective"]
cur   = rs.CurrentView()    # active view name
rs.CurrentView("Perspective")

# Set display mode
rs.ViewDisplayMode(cur, "Rendered")  # or "Wireframe", "Shaded"

Documentdoc

DocumentName / DocumentSaved / SaveFile () → str / bool

Example

import rhinoscriptsyntax as rs
name  = rs.DocumentName()    # "myfile.3dm" or None
saved = rs.DocumentSaved()   # False if unsaved changes
if not saved:
    rs.SaveFile()             # saves to current path

Blockblock

IsBlock / InsertBlock / BlockNames various → various

Example

import rhinoscriptsyntax as rs
blocks = rs.BlockNames()
print("Blocks in document:", blocks)

obj = rs.GetObject("Select")
if rs.IsBlock(obj): print("It's a block instance")

# Insert at origin, scale 1, no rotation
rs.InsertBlock("MyBlock", [0,0,0])

Groupgroup

AddGroup / AddObjectsToGroup / ObjectGroups various → str / int

Example

import rhinoscriptsyntax as rs
objs    = rs.GetObjects("Select objects to group")
grp_name = rs.AddGroup("BeamGroup")  # create named group
rs.AddObjectsToGroup(objs, grp_name)
print(rs.ObjectGroups(objs[0]))      # ['BeamGroup']

Materialmat

AddMaterial / ObjectMaterialSource / ObjectMaterialIndex various → int / bool

Example

import rhinoscriptsyntax as rs
obj     = rs.GetObject("Object")
mat_idx = rs.AddMaterial()
rs.MaterialColor(mat_idx, (200, 50, 50))
rs.MaterialShininess(mat_idx, 0.8)
# Tell object to use its own material
rs.ObjectMaterialSource(obj, 1)
rs.ObjectMaterialIndex(obj, mat_idx)

Hatchhatch

AddHatch / HatchPatternNames (curve_id, hatch_pattern, scale, rotation) → guid

Example

import rhinoscriptsyntax as rs
patterns = rs.HatchPatternNames()
print("Available hatches:", patterns)

crv   = rs.GetObject("Closed curve", rs.filter.curve)
hatch = rs.AddHatch(crv, "Solid", 1, 0)

Lightlight

AddPointLight / AddDirectionalLight / AddSpotLight various → guid

Example

import rhinoscriptsyntax as rs
pt_light  = rs.AddPointLight([0,0,10])
dir_light = rs.AddDirectionalLight([0,0,10], [0,0,0])
spot      = rs.AddSpotLight([0,0,10], 5, [0,0,0])

Linetypeline

ObjectLineType / ObjectLineTypeSource / LinetypeNames various → str

Example

import rhinoscriptsyntax as rs
obj = rs.GetObject("Object")
print("Linetypes:", rs.LinetypeNames())
rs.ObjectLineTypeSource(obj, 1)      # use object linetype
rs.ObjectLineType(obj, "Dashed")