Ruby sketchup

Ruby sketchup DEFAULT


First, a Story

Look up!, at the image above this introduction. The snippet of code captured in that image very closely approximates some of the first lines of Ruby that I ever wrote. I had spent a few hours learning some basic ruby syntax, then I dove into the SketchUp Ruby API with the express purpose of being able to pushpull more than one face at a time - a task repeated so regularly in the City Planning office I was working at where I created model after model of countless cities across the country. I couldn't believe how amazing it was that I could transform a task that can be so time consuming in SketchUp into a few simple lines of code that execute instantly. I saved myself days of double-clicking, pushpull, carpal tunnel laden time. NO, I saved my company days of time. What?! Give that man a raise!

Ok, no such raise came my way. But I did stumble on what has become a passion of mine and so many others - the SketchUp Ruby API. And if you're coming to this page and reading this for the first time, there is a decent chance that you are also on the verge of diving into the SketchUp Ruby API. So lets get started!

What is the SketchUp Ruby API

SketchUp is software that you can use to create 3D models of anything you like. Ruby is a super-powerful plain text programming language and an API an Application Programming Interface (API). Cool, but what does that mean. It just means that you can use the Ruby language to extend SketchUp to do more than it does out of the box. In my example, I wrote myself a quick new tool that gave SketchUp the ability to pushpull hundreds of thousands of faces instantly. Now let's see what you can imagine and add to SketchUp.

Where Should I Begin?

Arguably, I should have lead off with this information. Oh well, too late!

Take me to the Ruby API Docs - If you are familiar with API's, SketchUp, Ruby, etc and just need to find the Ruby API documentation, then click that link! Also, there is a link to it on the right side of this page that says "Check out the latest Ruby API". The API docs have all the documentation that regular consumers of API's need to get up and running quickly with our Ruby API.

I need help getting started - Fortunately for you, we have just the thing. In the Chapter Menu index on the upper right side of the page, you can find a section called "Getting Started". Go there! You will be taken to a series of basic lessons to help API beginners. These Getting Started lessons try hard to break everything down to simple terms, while being highly informative for just about anyone trying to get up and going as quickly as possible.

In Depth Examples - You should also review the section with Example Extensions. There we have example scripts that go well beyond the basics. We show how to package your extension for distribution to others, show many examples of best practices, and more. Once you get oriented and are considering sharing extensions, you'll want to get familiar with the examples in our Example Extensions section.

Thanks for coming and have fun!

Chris Fullmer and the entire SketchUp Extensibility Team

How to Use Ruby Scripts in Sketchup

By G.S. Jackson

Notepad++ lets you save MXML files.

If your business involves rendering 3D drawings or sketches of objects such as buildings or floor plans, you might know about Google SketchUp. SketchUp allows you to model 3D objects or import models into existing images. Furthermore, you can import various scripts from programming languages such as Ruby to extend SketchUp functionality. Importing Ruby scripts is as easy as copying Ruby source code into the SketchUp plugins folder.

Close Google SketchUp if it is currently running.

Download the desired Ruby script from the Web page that distributes it. If the script is zipped, unzip it.

Navigate to the SketchUp plugins directory in your operating system. For Windows computers, go to C:/Program Files/Google/Google SketchUp 8/Plugins. In Mac OS X, go to [hard drive name]/Library/Application Support/Google SketchUp 8/SketchUp/Plugins. (The number following "Google SketchUp" in the file path denotes the version of SketchUp you have installed.)

Copy and paste the Ruby script files into the directory. Restart SketchUp. Follow the instructions for the script's use, provided by the author of the script.


Writer Bio

G.S. Jackson specializes in topics related to literature, computers and technology. He holds a Bachelor of Arts in English and computer science from Southern Illinois University Edwardsville.

  1. Care bear cast
  2. Husqvarna workshop manuals
  3. Engineering manager jobs
  4. Daredevils suit
  5. Community helpers craft

The Ruby Console

In this lesson we'll execute some simple Ruby Script snippets inside of SketchUp and learn about the Ruby API Documentation. By the end of this tutorial, you should be able to:

  • Access the Ruby Console and use it to execute code.
  • Perform basic tasks on the Ruby Console using Ruby Code.
  • Use the Ruby API Documentation to learn more about specific API classes, modules, and methods.

Try it Now!

Open up SketchUp and find the Ruby Console. You can access it from the Window menu. Copy this snippet and paste it into the console and press enter to execute it.

1 + 2

That's a pretty simple example, but it is Ruby that took that simple math expression and returned a result. That is the basis for the rest of these lessons in the Getting Started section.

Controlling the Console

The Ruby Console is also controlable from Ruby itself. Check out this simple snippet that will let you know if the console is open:


Maybe you realized that snippet is fairly useless because we already know that the console is open, since we just executed code in it. However later you'll learn how to write ruby code, save it to a file and have it get executed when SketchUp starts, or when a user activates your code via a menu item. In those cases, sometimes its useful for you as the developer to know if the console is open so that you can output messages to it.

Now that we've executed a few things, the console is starting to get full of code and messages that sometimes get in the way. Here is how you would clear the console:


 Want an even easier way to clear the console?

Here's a helpful tip, you can also type into the console and execute that command to clear the conolse. Its not a Ruby method, so you can't use it inside of a Ruby file. It will only work when typed directly into the Ruby Console.

And lastly, you can also show or hide the console. Since you've got it open, lets go ahead and hide it. Here is what that code looks like:


Ruby API Documentation

How can you as a developer know all the methods and classes available to you? Through our Ruby API Documentation pages! For example, in this lesson you were able to interact with the Ruby Console via ruby because SketchUp adds API methods that let you do that. Get it? We have to expose control via the API, then you use the API to access anything that we have exposed control over.

You can find everything you need to know about how to manipulate the Ruby Console via ruby from the Console class page in our API docs. Go check that page out right now. You'll see all the available methods you can use to manipulate the Ruby Console, along with some sample snippets of code that begin to illustrate how to use that method.

What's Next?

The rest of these lessons continue using short snippets of code to execute specific tasks inside of SketchUp. You don't necessarily need to complete the lessons in any specific order, but some of the lessons will build on concepts taught in a previous lesson.

Ruby for SketchUp - Test size grouping and set color with Ruby Script

Edges to RubiesThe Complete SketchUp Tutorial


Farmer Ball (Ball Farm, on Ball Road) built Honeymoon House for his children. He thought they might enjoy some privacy as newlyweds. (Not on Ball Road, Honeymoon House is still just a short walk from the farm.)

Look closely at this charming home and you see something unusual. Clearly a bungalow, it features the hipped roof and hipped dormer that would later become typical of the Craftsman four-square. I strongly suspect that this home was builder-designed. It predates the Craftsman period by ten years!

Honeymoon House, Warwick, NY, 1895.

Honeymoon House, built by Farmer Ball for his children.

Hello, World!, chapter 11 icon

Chapter 11—Introduction to Ruby Programming

Why Write Rubies?

The basic idea is simple. You write a little program that automates some portion of your work. From then on, when you meet the same task again, you just run your little program. That portion of your work is gone.

In this half of the book, we'll create programs that will teach you enough to build a complete, Craftsman-style (or any other style) carriage house. Those who want to add Ruby power can stop after Chapter 17. (The final three chapters are for those who want to add fancy WebDialog interfaces to their programs.)

Late in this chapter you'll meet SketchTalk. Much more on this at the end of the chapter. For now, here's the idea:

  1. Model a Riser
  2. Model the Tread
  3. Add a Baluster
  4. Add Another Baluster
  5. Create a "Step" Component
  6. Move/Copy Up Rise, Out Run, 14x
  7. Add the Banister

Each one of those model actions is a single SketchTalk command. Your entire stairway will be built by a seven-line Ruby! (P.S. Oops. I forgot that you need to select everything before you make the component. Make that eight lines.) Here's the code for selecting everything and turning it into a component named "step":

Do you think you could write two lines as complex as those? OK, I'm kidding. Making things dead simple is a major goal in Ruby programming.

And if you've hung around the Sketchucation forums, you know that many Ruby authors share their Rubies—sometimes for money, often for free—with others. Some have become famous within the SketchUp community for their Ruby brilliance. Your tutor is hoping to launch a few more Ruby stars.

Before we get going, there are some administrative matters to handle. With these out of the way we'll install a Ruby and then start programming.

Three Classes of Readers

Some of you are new to programming. Some of you are programmers ranging from minimally skilled to aces, but you don't know the Ruby language. A few of you are Ruby programmers who want to master the SketchUp Ruby API. I want to optimize the use of your time for all of you. Here's how.

Text, such as this, is for everyone. This is where we'll cover the SketchUp Ruby API.

Topic: API

This is a programming beginners' section. If you've done some programming, just look at the topic. If you know that API is short for Application Program Interface, and you know what that means, skip the section.

If you are new to programming, an API is a defined set of routines that your code can use to take advantage of a product such as SketchUp. Let's say you've drawn a face and given that face the name "f". You want to PushPull it up eight feet. Here's the API you'd use:

f.pushpull 96

That will not be on the quiz. Just as in manual SketchingUp, you'll pushpull often in your Rubies.
Coders: Ruby is case-sensitive.

This is a coder's section. If you are a programmer, but don't know Ruby, the first paragraph (not this one, the one above) will state the point. If you understand the first paragraph, you can skip the rest of the section.

For non-programmers, in a case-sensitive language "foo", "Foo" and "FOO" are three entirely different things. In a case-insensitive language, those three are all the same. On a PC, for instance, those are three ways of getting to the same file. On a Mac, those are three different file names.

Throughout this book I've named the command PushPull to remind you of the keyboard shortcut. Since Ruby is case-sensitive, you can't say:

f.PushPull # this is an error!

Topic: Tim Toady

Some experienced coders love Tim. Some experienced coders heartily dislike Tim.

Who is this controversial fellow? Actually, "Tim Toady" is the pronunciation for the acronym "TMTOWTDI". That comes from the Perl programming language and it stands for There's More Than One Way To Do It. "It", a pronoun without an antecedent, is like the geek favorite "foo." It stands for nothing in particular, everything in general. Ruby, which was designed to be a better Perl, usually has lots of ways to do "it".

The anti-Tim camp has its center in the Python programming language (named after the British comedy troupe, Monty Python). They say, "There should be one, obvious way to do it."

In my blog I have a pet python named "Monty." Monty promises to have a big hug for Tim if they meet. You don't want a big hug from Monty.

Tim Toady # In a block like this I'll show Tim Toady alternatives. # Programming beginners can skip these blocks. They won't help you get # past the beginner stage. =begin This is an alternative form of comment. If you want to read Rubies written by others, you will want to understand the alternatives. The loop style I'll teach is less popular than another, Ruby-only style, for example. =end
Topic: Comments

If you know what comments are, skip this block!

Comments are text placed in a computer program that is ignored by the computer. It is written by the programmer for the benefit of those who come to the program later. (Remember when you program that you may be the person who comes to the program later. Will you remember what you were thinking a week later? A month later? A year later?)

The Tim Toady block above shows two comment styles. You can use the "#" character to enter a comment. It may start the line, or it may follow code:

# Time to pull up the walls w.pushpull 96 # 96 inches is 8 feet, US standard ceiling height
In Ruby you can also use "=begin" and "=end" as comment delimiters. They must be at the left edge of the comment block.
=begin This is a block comment. =end

Let's summarize this section. Plain text is for everyone.

Topic: Skip the section if you understand the topic.

Coders: Read the first paragraph.

If it makes sense, skip the rest.

Tim Toady:

Read it if you want to read other authors' Rubies.

Installing Rubies

Have you installed Rubies? Do you know where your Plugins directory is? You can skip to the next section.

When SketchUp starts, it runs all the Rubies in your Plugins directory. It recognizes Rubies because their files end with ".rb" or some other, "I'm a Ruby program!" extension. The Plugins directory depends on your SketchUp version and whether you have a Mac or a PC. With either, you can find the Plugins directory this way.

Entering a command in the Ruby Console.  

Open your Ruby Console (Window/Ruby Console). In the white input area, type exactly what you see to the left. (Remember, Ruby is case-sensitive. "SketchUp" won't work. It must be "Sketchup".)

Response from the Ruby Console.  

After you press Enter, you will see something like this.

The first line echoes your input. The second line is the address of your Plugins directory. (The one in Figure 11-2 is the address of your Plugins directory if you are running Sketchup 7 on a PC. The one in your Ruby Console is the one you want.)

Now you need a Ruby to plug in. Copy this text:

# file_new.rb - start my way! # Copyright 2009, Martin Rinehart # Not licensed: # remove copyright notice; # use in "how to program ..." material. # Licensed: everything else. require 'sketchup' def send_actions() Sketchup.file_new() Sketchup.send_action( 'selectSelectionTool:' ) end # of send_actions() unless file_loaded?( "file_new.rb" )"Plugins").add_item( 'New File ' ) { send_actions() } send_actions() Sketchup.send_action( 'showRubyPanel:' ) file_loaded( "file_new.rb" ) end
Shortly I'm going to tell you to type in the code, not copy it. Copying is fine here. There's a lot that needs to be explained here, but this is not the place. We'll get there.

This Ruby is short, but not simple. It replaces the Line tool with the Selection tool when SketchUp starts up and after File/New. (Actually, you have to assign keyboard shortcut "N" to "New File" in the Plugins menu. Then tap "N" to get File/New followed by Tools/Select. Back to the start of Chapter 10 if you've forgotten how to assign keyboard shortcuts.)

After you copy the code, open your text editor and paste it into a blank page. Save this into your Plugins directory named "file_new.rb".

Close Sketchup and restart. (Remember, SketchUp loads all the ".rb" files when it starts.) You should see the Selection tool's arrow cursor. Click the Plugins menu item and you'll see "New File" as one of the menu choices. As SketchUp starts in File/New state, it will do nothing if you click it. Draw a box and then click Plugins/File New.

Suppose you liked the Line tool default choice. How do you uninstall a Ruby? Simple. Go to your Plugins directory and delete it. Note: a more complex Ruby, lets say "foo.rb" might have other support files. If the author got it right, you will have a "foo" subdirectory under Plugins where all the support files live. If you see a "foo" subdirectory, delete it when you delete "foo.rb".

You now know enough to install plugins. Go to (think about the name) and browse. Find a free one that looks interesting, download and install it. When you come back, we'll do our first Ruby programming.

Hello, World!

Programming used to be a lot more complicated than it is today. A programmer meeting a new language was challenged just to get the computer to say "Hello, World!" Today that can be quite simple, but it's still a good place to start.

The SketchUp command to put a text string to the console is "puts". Back to your Ruby Console and in the white input area type:

Our first Hello, World!  

You should get a result like this.
The Console echoes your input. Then, in response, it puts the string you supplied in the console. Then it says "nil".

Coders: The Ruby keyword "nil" means "no value." It is returned by functions that don't return values, such as and it is the value of an uninitialized variable.

Topic: Constants

There are quite a lot of new concepts here. You typed "Hello, World!" with the quotation marks. That's called a "string constant." The value is actually the part between quotes. The quotes tell Ruby "string starts here" and later, "string ends here." They are called "delimiters." Note that the quotes disappear when your string is "puts" to the console.

There are other types of constants. The most common are numbers such as or .

The single- and double-quoted strings are not the same!

String substitutions via escaped characters are not performed within single-quoted strings. is not a newline. Within double quotes, is the symbol for a newline character.

Within single quotes there are two escaped characters: and (single quote and backslash).

Within double quotes there are many escaped characters. They start with the ones found in the C family tree:

  • —double quote
  • —backslash
  • —bell (alert)
  • —backspace
  • —newline
  • —return
  • —space
  • —tab
Tim Toady:There are lots of other ways to write string constants in Ruby. Many of them take this form:
%q/this is a single-quoted string/ %Q/this is a double-quoted string/ %/this is short-hand for a double-quoted string/ %q!you can use any delimiter you want! %Q[parens and brackets match in the regular fashion]

I almost never use these forms with one exception: if your string will include lots of double-quote and backslash characters these are handy as you don't escape these two characters.

Topic: Functions

A function is a tiny program. Typically you give it some value or values and it gives you back another value. is a call to a function named and a value, the string constant . It returns a string such as . Other functions, such as "puts" are called to do something (write to a file, for example). If the function does something that does not return a value, "nil" or nothing, is the return value.

OK, that said "Hello, World!". We've seen that the console is alive and well and will do what we tell it to do, provided we use good Ruby to tell it what to do. Talking with a console was programming until late last century. Today we have better alternatives.
Topic: UI

UI is short for User Interface. It is the way your computer program communicates with a person using your computer program. Modern UI work—including windows, multiple fonts, mice and the other things you think of when you think of using your computer—was invented at Xerox's Palo Alto Research Center, Xerox PARC. Xerox did not know what to do with it.

In 1978, Steve Jobs, then Apple CEO, saw it and was blown away. He had seen the future. The Apple Lisa (a 1983 flop) and Macintosh (a 1984- enduring success) were not far behind. Microsoft saw Apple's work and, detouring through an ill-fated partnership with IBM, created Windows. Windows 3.0, the first successful version, was released in 1990.

Let's say "Hello, World!" but from a 21st century UI. We'll need to create a window, with facilities to move the window around the screen, spots that will respond to mouse clicks and the text "Hello, World!" should be in the window. Complicated stuff!

A modern Hello, World!  

Fortunately, the complications have all been worked out by others. You need to do this.
That's right, you use the function to put a string constant up on the screen in a contemporary window. Grab the title bar and drag it around the screen. When you're ready to write your first Ruby, close it and rejoin us.

Ruby Programming

A "real" program is one that lives in a file. You can execute the program by "running" the file. Let's write our first program to see what this feels like. For starters, we'll need a directory where we can store our Ruby files. On my machine, holds Ruby programs. Make something that suits you on your machine. (Whatever you name it, make it easy to type. You'll be typing it a lot!)
Coders: First, you'll need a text editor that knows Ruby.

A word processor writes lots of things other than what you type into its files. That won't work at all.

On the PC, many SketchUp Ruby programmers use Notepad++. It's free and worth far more.

Topic: ++ (increment) Operator

Made popular by the "C" programming language, the operator increments (adds one to) a counter.

count = 0 count++ # count now equals 1 count++ # 2 ...
The "C++" language was cleverly named. It added object-oriented programming capability to the C language. Therefore it was C made better. Since then any number of people have used "foo++" to suggest an improved "foo".
Notepad++ is much too modestly named. It's a real programming editor that supports programming in lots of languages, including Ruby. Google for a download location in your country.

I know you want to write your first Ruby program. Don't press on using some piece of junk editor. Take the time now to get a real editor and begin learning how to use it. This is a small investment with a huge return.

Here's the entire program I want you to write. (Warning: copying the code is certainly possible. But you won't learn programming. You need to actually transfer the code through your fingers into your editor to learn to program. Programming is typing code.)

# /r/hw1.rb - our first Ruby program require 'sketchup' UI.messagebox( "Hello, World!" ) # end of /r/hw1.rb
The first and fourth lines (when I say fourth line, the count does not include the blank lines) are comments that specify the start and end of the file. They let you check when a previously running program fails. When your car stops, the first thing to check is the gas. When your code stops, first check that you still have the full file.

Note that in the comment I've used the forward slash, which won't work in Windows. It will work in Ruby, which makes the appropriate correction if you are using Windows.

Coders: In Ruby you or supporting files.

Loading means actually reading from disk into memory. Requiring tells Ruby to load only if the file has not already been loaded.

The second line loads the 'sketchup.rb' file unless it has already been loaded. (You can skip the ".rb" extension for , but not for . Don't ask because I don't know.)

The third line is one you've already seen, but with added parentheses. Passing a string constant or other value(s) to a function is done this way in every language I've used, except Ruby. Many times, but not all, Ruby will warn you that using parentheses is good practice to be sure your code is compatible with future versions. From now on, except in SketchTalk, I'll use parentheses.

OK, you've typed those lines into your own editor and saved the result as "hw1.rb". It's in the comment so I won't have to keep repeating where the file gets saved, right?

Running a Ruby program from the Ruby Console  

How do you run the program? The answer is on the left.
Again, try it out. Drag it around. Close it. Congratulations! You've written a SketchUp Ruby plugin. (Sure. It's useless. But as your tutor, I don't think it's useless. I think you have begun the journey.)

Topic: Imperative Programming Paradigm

Really big words. Really small topic.

There are lots of ways to write programs. A collection of related programming techniques is called a "programming paradigm." In "imperative programming" your program is a series of commands to the computer: do this, do that, do the other.

Contrast "imperative" with "procedural" programming. In the latter you tell the computer what you want done: . You don't explain the exact steps needed to sort. You tell the computer that's what you want. The computer (actually, some unsung programmer hero who came before) knows how to sort.

Let's use "hw1.rb" to create "hw2.rb", a program that emphasizes the imperative nature. The darker green lines show changes, the pink shows an addition.
# /r/hw2.rb - our second Ruby program require 'sketchup' UI.messagebox( "Hello" )UI.messagebox( "World!" )# end of /r/hw2.rb


You get "Hello" first.


Then "World!".

Topic: Sequential Execution

More big words for a simple concept.

The normal order of execution of statements in a program is in sequence, top to bottom.

To close this chapter we'll take a brief look at SketchTalk. That will get you modeling first from the Ruby Console and then from another Ruby you will write. Using SketchTalk requires that you know a little (actually, very little) 3D geometry.

Basic 3D Geometry

3D geometry is the topic of thick textbooks that your tutor has not read. A very few terms and concepts are all that's needed to understand the SketchUp Ruby API. That's all we'll need.

If you recall a little high school math, you remember graphs showing X on the horizontal axis, Y on the vertical axis. We'll start there.

Topic: Integers and Real Numbers

Integers are counting numbers: 0, 1, 2, ... They can also be negative: -1, -2, ...

Real numbers (horrible name!) have a decimal part: 1.0, 3.15, -333.333. Real numbers may also be called "floating point" numbers.

If you deal with very large or very small quantities you can specify the number of places to shift the decimal point this way: 14.5e9 is 14.5 billion; 2e-14 is the size, in centimeters, of a proton. (I don't know what sort of tape measure you use for this.)

Coders: In Ruby you can insert underscore characters for readability in large numbers: 1_000_000 is one million.

Coders: In Ruby an array can be written, enclosed in square brackets such as or . Array indexing starts at zero.

An array is a list of things. The array is the whole list. An individual element can be selected with a subscript. Subscripts in Ruby programming (and in most computer languages) are integers enclosed in square brackets. For example, assume: . Then is 'Bob'. is 'Carol' and so on.

Topic: Origin

In 2D geometry the "origin" is the point [0,0]. The X and Y axes cross at the origin.

In 3D geometry the origin is the point [0,0,0]. The X, Y and Z axes cross at the origin. In Sketchup, the red, green and blue axes cross at the origin.

Topic: 2D Point

A pair of numbers, which we will write as a Ruby array () locates a point in 2D geometry. By convention, the first number locates the point on the X axis, the second number is the Y location. is 2 units right of the Y axis, 3 units above the X axis.

Topic: 2D Vector

A "vector" in 2D geometry is also a pair of numbers. It specifies a direction and a distance. moves 4 units right and 5 units up. If there is no starting point specified, vectors start at the origin.

A starting point and a vector combine to form a line.

Now let's use our knowledge of 2D geometry to extend to 3D geometry. Mathematicians add the Z axis. In SketchUp the axes are colored red, green and blue and from now on we will call them "r", "g" and "b".
Topic: 3D Point

In 3D geometry a point is located on the "X", "Y" and "Z" axes, conventionally written . From 2D geometry, the Y axis was vertical and the X axis was horizontal. Mentally take a piece of paper, tape it to the wall and draw the X and Y axes.

Sharp pencil balanced on its eraser  

To get to 3D, take that piece of paper off your mental wall and lay it on a mental desktop so that the Y axis goes away from you as it gets higher and toward you as it gets more negative. The X axis is positive toward your right; negative towards your left. Balance a sharp wood pencil on its eraser at the X,Y origin. That is the beginning of the Z axis with higher values up, negative values down.

To locate a single point in 3D space, provide values for X, Y and Z axes.

In SketchUp, orbiting lets you fly around your model. The g and b axes can be positioned anywhere. This means that X, Y and Z no longer make much sense. Just use r, g and b, and remember the convention that the solid axes are positive, the dotted ones negative. The b axis is usually the vertical axis.

You can use a SketchUp object. For example: . You can also use an array of three numbers almost anywhere you need a point: . As the latter is much easier to type, we'll almost always use it.

Topic: Plane

In geometry (not at the airport) a plane is a flat surface extending infinitely. Think of it as a piece of paper—no folds, bends or wrinkles—with no thickness and no edges.

Topic: 3D Vector

A 3D vector is analogous to the 2D vector: it's a direction and distance. When we build our stairway (7 inch rise, 9 inch run, parallel to the red axis) we'll use , a vector that specifies no change in the red, 9 inches along the green axis and 7 inches along the blue (up) axis.

Topic: Vertex

A vertex is a point at which lines meet or cross. If you have more than one vertex, you have "vertices."

Topic: Orthogonal

In SketchUp the planes formed by any two axes (rg, gb or br) are orthogonal. Anything you model with lines and faces parallel to these planes is orthogonal.

A SketchUp face is a small portion of a plane. It has an inside and an outside. More exactly, there is a vector called the face's "normal" that points away from the outside. Let's Rectangle from [0,0,0] to [10,20,0]. That creates a face in the rg plane. If that face's normal is [0,0,1], the outside is facing up. Face down the normal is [0,0,-1].

Ready to put theory into practice? Let's start modeling with SketchTalk.

Modeling with SketchTalk

What is SketchTalk? It's some Ruby I've written. It's easier to demonstrate than to explain.

In our Companion Packages page download a copy of the SketchTalk package. We will be continuously working on so don't bury it in the Plugins directory. It will be much easier if you extract it to your convenient working directory.

That package includes and , the functions and classes, respectively, that make up SketchTalk. It also includes that you can open in your favorite browser for a summary.

Loading SketchTalk  

Begin by loading .

Drawing a line in SketchTalk  

The initial character here is the letter that starts the word "letter", the SketchUp keyboard shortcut for the Line tool. In many fonts you can't see much difference between "" and the digit "". SketchTalk builds on the keyboard shortcuts, so we have to put up with this problem. Here you typed:

into your Ruby Console.

Almost magically, a line appears in your model between the two points.

The Ruby Console reports that it is a "Sketchup::Edge", which is much more precise. It's an "Edge" object defined in the "Sketchup" module. (Other modules could have other Edge objects. We won't get confused.)

Drawing a rectangle in SketchTalk  

The Rectangle tool is grabbed by "r". Type the following into the Ruby Console:

You get the rectangle in your model. In the Ruby Console output you see that you've got a Rectangle object including a face, edges and other information. More, much more, on that later.

Drawing a box with SketchTalk  

SketchTalk doesn't have all the SketchUp tools. For example, there's no Orbit. (Why would your computer want to orbit your model? It wouldn't know what it was looking at. Computers are dumb.) Then, SketchUp doesn't have all the SketchTalk tools. First among them is . Type:

into your Ruby Console. (Maybe it's your SketchTalk console?)

draws a Rectangle, then grabs the PushPull tool to leap into 3D existence.

You might want to try some more boxes on your own. This one shows that our boxes don't have to start in the rg plane.

Why -10? Try it and see. Due to no small effort, orthogonal SketchTalk boxes always PushPull toward the positive end of an axis, unless the distance is negative.

Practice a bit with these tools until you begin to think in 3D points. In Chapter 12 we'll start in the basement and then we'll use these to model that eight-command stairway. And you'll also use the command. Yes, that is one sweet command!

Showing off the carriage house.View of apartment contents.Donut component. Chapter 12 icon.

Sketchup ruby

SketchUp Ruby API

The SketchUp Ruby API allows you to interact with SketchUp models and the SketchUp application. It is available from within SketchUp, it cannot be used by itself.

Get started with the Ruby API Overview.

Visit our SketchUp Developer Center for more information and resources on SketchUp's APIs.

LayOut API

As of SketchUp 2018 you can also create and manipulate LayOut documents. For more information refer to the LayOut API Overview.

Currently the LayOut Ruby API is only available from SketchUp.

Examples and Tutorials

Getting Started

To get you started we have a collection of examples of tutorials. These will take you through various common scenarios and concepts of the SketchUp API.

Ruby C Extensions within SketchUp

Ruby itself allows you to work with Ruby code via C (and C++). This allows for more complex functionality and possible performance improvements. We provide examples on how to create Ruby C Extensions that work with various SketchUp versions and platforms:


To make debugging SketchUp Ruby extensions easier we have a Ruby debugger interface that can be added to your SketchUp installation. This will let you use the debugging functionality of IDEs/editors that support the Ruby Debug protocol:

We also have a guide on setting up RubyMine as an example of how you can set up your debugger:


The standard testing frameworks for Ruby usually assume your tests are run from Ruby's console interpreter. This pose a problem when you want to set up unit tests for your code that needs to run within SketchUp.

To address this we created TestUp, a wrapper on top of Minitest that works within SketchUp along with a GUI interface to manage your tests.


Give your IDE insight to the SketchUp Ruby API by feeding it stubs:

As an example of how to set up your IDE we created an example that describe the process for RubyMine:

VSCode example:


If you find a typo, unclear description etc in the documentation, please log a new issue in the issue tracker for our APIs:

Ruby Code Editor SketchUp Extension (v.3.0)


The extension warehouse was first included in sketchup 2013. In order to use it, open sketchup and go to Window---->Extension Warehouse. Sign with your google account and explore through wide arry of extension categories. You can also look for any particular extension. Afer discovering your favorite extension, just click on install option and abide by the instructions.

SketchUp and .rbz files: The SketchUp 8 and newerer versions will facilitate the users to set up zipped Ruby files (.rbz) and open it inside sketchup. If there is a standard (.zip) extension with the plugin, then the extension name can be modified from .zip to .rbz.

Go through the following processes to learn how to set up a SketchUp Ruby plugin script through the .rbz format:

  • It is suggested that the users should log in their computer as an admin prior to set up any Ruby scripts as it will simplify the installation process and make sure that all the files are set up in the suitable places.
  • Go to Window > Preferences (Windows) or SketchUp > Preferences (Mac OS X). The Preferences dialog box is displayed.
  • Turn on Extensions. The Extensions panel will be visible.
  • Select the Install Extension button. The Open dialog box is appear.
  • Find the Ruby zip file to set up (.rbz).
  • Select the Open button. The Ruby plugin will be shown in the extension lists.

*.rb files: In case you contains a file having the .rb extension, the plugin can be set up with the placement of the Ruby script file into the exact folder. After that restart SketchUp.

Windows - the default location for various sketchup versions will be as follow:

  • SketchUp 2015:C:\Users\YOUR USERNAME\AppData\Roaming\SketchUp\SketchUp 2015\SketchUp\Plugins
  • SketchUp 2014:C:\Users\YOUR USERNAME\AppData\Roaming\SketchUp\SketchUp 2014\SketchUp\Plugins
  • SketchUp 2013: C:\Program Files\SketchUp\SketchUp ####\Plugins.
  • SketchUp 8 and older: C:\Program Files\Google\Google SketchUp #\Plugins.

For Mac OS X - the default location will be as follow:

  • Version 2013 and higher: Open a new Finder window, press and hold the Option key from the keyboard, then select Go in the menu bar> Library > Application Support > SketchUp # > SketchUp > Plugins
  • Version 8 and earlier:[YOUR USER NAME]/Library/Application Support/Google SketchUp #/SketchUp/plugins

It is recommended to generate your plugins folder in the SketchUp folder by selecting File > New folder in your Finder window.

After reopening SketchUp, one will find that the script's commands are included with the proper menus. The script can also function through the Ruby Console (open the "Windows" menu, and then select Ruby Console).

How to set up Ruby Extensions in Sketchup


You will also like:

Getting Started & Tutorials

Example Extensions

We often find that we need a level of training that goes well beyond the basics, but is more informative than just reading the API documentation. Look no further! Check out our Example Extensions section for examples of fully functioning SketchUp Extensions, complete with comments and helpful hints.

How Do I Use These Tutorials?

Hopefully you can use these examples however you want. The Example code is available 3 different ways. You can:

  1. Read the Example Extensions tutorials on the SketchUp Developer website. Read through the step by step tutorial of the code and comments and try to follow along by building the same extension yourself. Use these examples to help learn better SketchUp API usage.
  2. Fork the fully commented examples from Github. Get the code right on your machine, with all the comments for easy access. Use it as a quick reference to comments, code snippets, etc.
  3. Fork the non-commented version from Github. This is handy for people who just want to look at the code quickly and move on. You can copy and paste chunks of code easily from the non-commented samples without the verbose comments getting in the way.

Depending what you are trying to achieve, there is a method to get there easily. Just get all the code at once, and pull out what you need. Or follow along line by line, tutorial style. The end goal is for everyone to gain access to solid code examples that help improve their SketchUp extensions.

Loading Directly from the Repository

If you clone this repository to your computer you can load the files directly from where you cloned them using a proxy loading script:

# Create a file in your Plugins folder with these lines: $LOAD_PATH << 'some\path\to\sketchup-ruby-api-tutorials'require'load_tutorials.rb'

That snippet will take care of loading the examples and tutorials.

If you have examples of your own that you think might be useful open a Pull Request. Follow the pattern of the existing examples.

You can use while you work to reload all the files.

Also make sure to check out the Wiki section for guides on how to setup your project for extension development, IDE setup and more.


2071 2072 2073 2074 2075