Part 1 shows how to set up the Eclipse environment to create, edit, and execute SketchUp scripts. It provided an example script, but left an important question unanswered: How does the code inside the scripts work? The goal of this article is to answer this question by discussing the SketchUp API. The SketchUp API contains classes whose methods draw and modify aspects of a SketchUp design, including lines, surfaces, colors, and images. This article can't cover the entire API, so I focus on the basic classes needed to construct SketchUp shapes. But first, because the SketchUp API is based on Ruby, I provide an overview of what the Ruby language is and how it works.
Ruby for Java programmers: A brief introduction
Given the popularity of the Java™ programming language and the mention of Eclipse in the title, I assume you're familiar with the Java programming language. Ruby isn't nearly as popular, so I briefly explain some of the similarities and differences between the two. In this way, I hope to make you sufficiently comfortable with the language to dip your toes in and write some elementary commands.
- Like the Java language, Ruby is object-oriented. In fact, everything
in Ruby is a subclass of
Object. There are no primitives like the Java language's
- You don't have to declare variable types in Ruby, so you can set x equal to 5 in one command and x equal to "Hello world!" in the next.
- Ruby methods are invoked with the same dot-notation as in Java programming,
but parentheses (
()) and semicolons (
;) are optional. Every Ruby class has a constructor method called
Stringobjects can be surrounded by double quotation marks (
") or single quotation marks (
'); the difference is that the interpreter recognizes escape sequences (
\t, etc.) inside double-quoted
Stringobjects. Ruby accepts single-character
Stringobjects, but doesn't have a separate data structure for
- Single-line comments start with the pound sign (
#). Multi-line comments are delimited by
- Ruby classes serve the same roles as Java classes, but in addition to classes, Ruby supports modules. A Ruby module is like a Java class that contains only static methods. You can't instantiate a Ruby module; it's just a collection of routines under a distinct namespace.
- The most common text output methods are
puts, which adds a newline to the end of the output, and
With these rules in mind, you're ready to start experimenting with Ruby code. In SketchUp, click Window > Ruby Console. Then try any or all of the following commands:
2 * (5 + 5) / 4 * 1.0
print 'Hello world'; puts '!'
m = Time.new; m.month
x = [4, true, 'hi there!']
puts x.to_s + " is a " + x.class.to_s
In the last command, the
to_s method of Ruby's
Object class performs the same operation as the
toString() method in Java's
class: It returns a
String that represents the
Object. Figure 1 shows the results of these commands displayed in SketchUp's
Figure 1. Output in the Ruby Console
These commands may seem simple, but Ruby provides features that aren't
anything like what you'll see in the Java,
C++ languages. Such unique features include iterator
blocks, parallel assignment, and oddities like the
class. But when it comes to the SketchUp API, you can go very far with just a basic
understanding of the language. The next section discusses the API in detail.
The SketchUp API
Part 1 provides an example SketchUp script and explains how to
execute it using SketchUp's
load command and the
SketchUp Bridge. But the article doesn't explain how the script works. The
script's commands are part of the SketchUp API — the subject of this section. I
present the fundamental SketchUp data structures first (
Model), then explain how to create
After that, I explain the two extrusion methods —
followme— and conclude with a
description of how SketchUp materials are applied to objects.
The fundamental data structures
A Ruby module is a collection of methods; the SketchUp module is the most important module in the SketchUp API. Its methods provide information related to the entire SketchUp installation, and five of them are listed here:
os_language— Returns the operating system on which SketchUp is running
locale— Returns the language code for the current locale
find_support_files— Returns the path of files within the top-level SketchUp directory
version_number— Returns the version of SketchUp
active_model— Returns the
Modelobject representing the current design
Like a static method in the Java language, you invoke a Ruby module's method by
following the module name with a dot and the name of the method. For example,
to find the version of the SketchUp application, you could enter the following
command in the Ruby Console:
Of all the methods in the SketchUp module,
active_model is the most important. It returns the
Model object that contains all the information in
the current SketchUp design. Each design has a single
Model object, and each
object embodies a single design. By "all the information," I mean that the
Model object stores the positions of every vertex,
the color of every shape, the styles available for the design, and much more. The
Model stores its information in a series of container
objects, which include the following components:
Entities— All the shapes in the current design
Materials— Colors and textures
Layers— The design's graphic layers
Styles— The appearance settings for the design
Generally speaking, the goal of a SketchUp script is to modify the data in these container
objects. To do this, call the corresponding method in the
Model class. These methods are easy to remember: The
layers method returns the
styles method returns the
Styles object, the
method returns the
Entities object, etc. For
example, the following code retrieves the
container of the current
model = Sketchup.active_model ents = model.entities
You can combine these into a single command:
ents = Sketchup.active_model.entities
This is an important command to know, as all of the example scripts in this article
begin with this line. You can download the example scripts. Next, I explain why it's so important to
be able to access the
Entities container of a
SketchUp entities: Edges and Faces
As you might expect, the
Entities container contains
Entity objects. Put simply, an
Entity object represents any shape that can be
seen, moved, or modified within the SketchUp design window. The
Entity class is the superclass of many of SketchUp's
classes, as shown in Figure 2, which shows most of
Figure 2. Entity class hierarchy
The most important
Entity objects are the
which serve as the building blocks of every shape in a SketchUp design. An
Edge is a line segment, and you add
objects to a design through the
add_line method of the
Entities class. This method accepts two three-element
arrays that represent the
Edge object's starting and
ending points. For example, to create a line segment from [0, 0, 0] to [5, 5, 5], you
could use code like the following:
ents = Sketchup.active_model.entities edge = ents.add_line [0,0,0], [5, 5, 5]
When the second command executes, SketchUp automatically draws the line corresponding
Edge object in its design window. You can
read and modify the line's properties by calling methods of the
Edge class. For example, the
length method returns the line's length,
start returns its starting point, and
end returns its ending point. There are also methods
that change the line's appearance.
As its name implies, a
Face object represents a
2-D surface. The
method of the
Entities class both draws the surface
in the design window and returns a
This method accepts a set of points or
For example, the following code creates two
objects — one in the x-y plane and one in the y-z plane. Both
Face objects have four vertices, but you can create
Face with any number of points.
ents = Sketchup.active_model.entities # Create a face from points face1 = ents.add_face [0,0,0], [3,0,0], [3,3,0], [0,3,0] # Create a face from edges edge1 = ents.add_line [0,0,0], [0,3,0] edge2 = ents.add_line [0,3,0], [0,3,3] edge3 = ents.add_line [0,3,3], [0,0,3] edge4 = ents.add_line [0,0,3], [0,0,0] face2 = ents.add_face [edge1, edge2, edge3, edge4]
The methods of the
Face class access the properties
of the corresponding shape. The
returns the surface area, the
edges method returns
the array of
Edge objects that form the face, and
normal method returns the surface's normal
vector, which identifies the direction perpendicular to the surface. For
[0, 0, 1] because the +z direction is perpendicular
to the x-y plane. Of course, the
[0, 0, -1] vector
is also perpendicular, and you can flip the
object's normal vector by calling the
Extruding 3-D figures
The process of forming a 3-D figure from a 2-D surface is
called extrusion. The
Face class contains
two methods that perform extrusion:
followme. It's important to note that SketchUp
doesn't have a separate class for 3-D figures. Instead, during the extrusion process,
SketchUp creates the
Face objects that form the figure.
pushpull method is the easier of the two methods
to use, and it performs the same operation as SketchUp's
pushpull tool. That
is, it creates a 3-D figure by extruding in the direction of the
Face object's normal vector. Its only required
argument is a numerical distance that identifies how far the extrusion should
be performed. This value can be negative to extrude in the direction opposite
Face object's normal vector. For example, the
previous article formed a box by creating a square
Face object and calling the
pushpull method with an argument of
The second extrusion method is
followme, which serves
the same purpose as SketchUp's
followme tool. Although
pushpull only extrudes in a single direction,
followme extrudes in whatever direction you like.
For example, if you create a circular
you can form a cylinder by extruding along the circle's axis. But you can also
create a torus or sphere by extruding along a circular path. To set the extrusion
path, you need to define an
Edge object or an
Edge objects. This usage is shown in
Listing 1, which creates a triangular face and extrudes
it along a rectangular path (also see Download).
Listing 1. Extruding with the
# Access the Entities object model = Sketchup.active_model ents = model.entities # Create a triangular face triangle = ents.add_face [1, 0, 0], [0, 1, 0], [0, -1, 0] # Create the extrusion path path = ents.add_edges [0, 0, 0], [0, 0, 10], [0, -10, 10], [0, -10, 0], [0, 0, 0] # Extrude the triangle along the rectangular path triangle.followme path
add_edges method creates an array of
Edge objects from a sequence of points.
Figure 3a shows the triangular
object and a rectangular path. Figure 3b shows the result
of the last command of the script (
which extrudes the triangle along the path.
Figure 3. SketchUp extrusion
Note that the path must be a closed loop — that is, the first point of the first
Edge object in the path must have the same location
as the last point of the last
Now that you know how to build shapes in code, you need to know how to define
the appearance of those shapes. You do this by creating a
Material object, configuring its appearance, and
associating it with a shape such as an
Face object. You can define a
Material object's appearance by a color, a texture,
or both. The more detailed the
the more realistic and professional the drawing will look. SketchUp provides a
number of existing materials. To see what they look like in SketchUp, click
Window > Materials.
Just as the model's
Entities container holds
Entity objects, and the
Material objects. To add a new
Material object to your design, you need to invoke
add method of the
class. This method accepts a name for the material and returns a new
Material object. For example, the following code
Materials container and creates a
Material object named
mats = Sketchup.active_model.materials rb_mat = mats.add "RedBrick"
After you've created a
Material object, you can access
and configure its properties with methods in the
class, which include the following:
color— Sets the color of the
texture— Identifies the texture of the
materialType— Returns a number that identifies whether the
Materialobject has a color (
0), a texture (
1), or both (
display_name— Returns the name of the
SketchUp provides a specific
Color object, but it's easier
to substitute a simple RGB array like
[64, 128, 255].
Here, the first element identifies the intensity of red in the color, the second
identifies the intensity of green, and the third identifies the intensity of blue.
You can also substitute the name of a color, such as Red, Plum, or
MintGreen. To see the full list of X11 color names, type
Sketchup::Color.names in the Ruby Console. For
example, to color
rb_mat red, you could enter either
of the following commands:
rb_mat.color = [255, 0, 0] rb_mat.color = "Red"
In 3-D graphics parlance, a texture is an image applied to a design area like
wallpaper pattern: The image is repeated or cut as needed to cover the surface.
SketchUp provides a specific
Texture object, but it's
easier to substitute the image file name. SketchUp can create textures from
JPG, PNG, PSD, TIF, TGA, and BMP files, and the following command shows how
the image in C:/scripts/tex.targa is made the texture of a
Material object called
rb_mat.texture = "C:/scripts/tex.targa"
After you've configured a
Material object's color
or texture, assign it to a shape (or multiple shapes) in the design.
Doing so is simple: The
Entity, superclass of
a method called
material that accepts a
Material object and applies the
Material object's color or texture to the element.
This is shown in Listing 2, which creates a
Material object with a texture (C:/scripts/brick.jpg) and
a color (DodgerBlue). The path of the image file is defined in the first line; the script
won't work unless the path is identified correctly.
Listing 2. Creating and applying a material
image_file_path = "C:/scripts/brick.jpg" # Create the new material mats = Sketchup.active_model.materials brick_mat = mats.add "red_brick" # Assign the color and texture brick_mat.texture = image_file_path brick_mat.color = "DodgerBlue" # Draw a Face and set its material ents = Sketchup.active_model.entities face = ents.add_face [10, -10, 0], [10, 10, 0], [-10, 10, 0], [-10, -10, 0] face.reverse! face.material = brick_mat
Note that the color of
brick_mat is defined after
its texture to change the color of the texture before it's applied to the surface.
Though the brick.jpg image is primarily red, the final texture is blue,
Material object's color is defined
afterward. Figure 4 shows what the blue color looks like.
Figure 4. Material applied to a face
More to learn
I'd feel guilty if I let you think that all SketchUp scripts had to offer was
Material objects. SketchUp provides many more
fascinating capabilities that go far beyond making pretty shapes. They include:
- Animation— Define how a SketchUp design moves over time
- Component— Create modular design pieces that can be stored in files and instantiated within designs
- PolygonMesh— Create or import sophisticated shapes and apply complex textures
- WebDialog— Interact with the Internet through a specialized DHTML window
- Tool/Menu/Page— Add capabilities to SketchUp by augmenting the UI
And of course, one of SketchUp's strengths is the ability to interact with Google Earth and create geography-specific structures.
By creating and executing SketchUp scripts, you can automate the design process and
potentially save yourself a great deal of time. In addition, you can code geometric
algorithms that draw shapes like splines, nonuniform rational B-splines (NURBs),
and parametric curves. Thankfully, the SketchUp API keeps to the same
simple-but-powerful mindset that has made Google so successful. In just a small
amount of time, you can master the basic classes (
Face) that combine to form SketchUp figures. And as you
invest further time, you can add advanced capabilities like animation and dynamic
|Eclipse plug-in that interfaces with SketchUp||os-eclipse-sketchup2-example_scripts.zip||16KB|
- The classes that make up the SketchUp API are listed in the SketchUp Ruby Documentation and you can click each class name to view its methods.
- For tutorials and demonstration videos, visit Google's training site to learn more about how this tool works.
- For more information about Ruby, check out the Ruby Documentation.
- Check out the "Recommended Eclipse reading list."
- Browse all the Eclipse content on developerWorks.
- Follow developerWorks on Twitter.
- New to Eclipse? Read the developerWorks article "Get started with the Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins.
- Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
- To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
- Stay current with developerWorks' Technical events and webcasts.
- Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
- Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
- Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
Get products and technologies
- Download the SketchUp Bridge archive.
- Check out the latest Eclipse technology downloads at IBM alphaWorks.
- Download Eclipse Platform and other projects from the Eclipse Foundation.
- Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
- Innovate your next open source development project with IBM trial software, available for download or on DVD.
- The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
- The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
- Participate in developerWorks blogs and get involved in the developerWorks community.