Developer's Guide

The Google SketchUp Ruby API lets you extend the functionality of SketchUp as well as create macros to encapsulate complex tasks.

Contents

Introduction

In this example we write a script to draw a set of stairs in the SketchUp model. Using your favorite editor, create file called stairs.rb and insert the followin line at the top:

require 'sketchup'

Drawing Stairs

Next you will define a function, draw_stairs that will add geometric objects into the SketchUp model.

def draw_stairs
  # variables to control the maximum step height and depth
  max_step_height = 8
  max_step_depth = 12
  step_width = 36

  p1 = Geom::Point3d.new(0, 0, 0)
  p2 = Geom::Point3d.new(100, 0, 100)

Note that module Geom and class Geom::Point3d are part of the Google SketchUp Ruby API. Units are in inches. Next, compute the height and length of height and length of the staircase.

  h = (p2 - p1).z
  puts "height = #{h}"
  p3 = Geom::Point3d.new(p2.x, p2.y, p1.z)
  v2 = p3 - p1
  l = v2.length
  puts "length = #{l}"

Compute the number of steps needed and compute the vectors to create each step.

  n1 = (h / max_step_height).to_i
  puts "n1 = #{n1}"
  n2 = (l / max_step_depth).to_i
  puts "n2 = #{n2}"
  numSteps = [n1, n2].max
  puts "numSteps = #{numSteps}"

  v1 = Geom::Vector3d.new 0, 0, (h/numSteps)
  v2.length = l/numSteps
  v3 = v1 * v2
  v3.length = step_width

Retrieve a reference to the SketchUp model and its entities.

  model = Sketchup.active_model
  entities = model.entities

Now perform the operation of creating the staircase, iterating the number of steps and drawing a step with each iteration.

  edges = []
  model.start_operation "Stairs"
  pt1 = p1
  for i in 1..numSteps
      # create the front of the step
      pt2 = pt1 + v1
      pt3 = pt2 + v3
      pt4 = pt1 + v3

      edges[0]   = entities.add_line(pt1, pt2)
      edges[1] = entities.add_line(pt2, pt3)
      edges[2] = entities.add_line(pt3, pt4)
      edges[3] = entities.add_line(pt4, pt1)
      entities.add_face edges

      # now make the top
      pt1 = pt2
      pt4 = pt3
      pt2 = pt1 + v2
      pt3 = pt4 + v2

      edges[3] = edges[1]
      edges[0] = entities.add_line(pt1, pt2)
      edges[1] = entities.add_line(pt2, pt3)
      edges[2] = entities.add_line(pt3, pt4)
      entities.add_face edges

      # move to the next step
      pt1 = pt2
  end

  model.commit_operation
end # def draw_stairs

Note that the operation was put onto the undo stack of the model by enclosing the operation with model.start_operation "Stairs" and model.commit_operation

Add a menu item

Now we are ready to add a menu item to SketchUp that will execute the drawing of the stairs. We will do with by using the UI class of the API. We can access application menu bar of SketchUp through the class attribute @@menu of the UI class.

UI.menu("PlugIns").add_item("Draw stairs") { draw_stairs }