3-D modeling with SketchUp and Eclipse, Part 1: Creating the bridge between SketchUp and Eclipse

Matthew Scarpino (mattscar@yahoo.com), Java Developer, Eclipse Engineering, LLC

Matthew Scarpino is a project manager and Java developer at Eclipse Engineering LLC. He is the lead author of SWT/JFace in Action and made a minor but important contribution to the Standard Widget Toolkit (SWT). He enjoys Irish folk music, marathon running, the poetry of William Blake, and the Graphical Editing Framework (GEF).

Summary: One of Google's most recent and popular tools, SketchUp, takes the pain out of 3-D modeling. Not only does SketchUp make it easy to create designs manually but it also allows you to automate the design process with Ruby scripts. Because managing and editing these scripts is so important, it helps to have a full-featured development environment like Eclipse. Learn how to configure SketchUp and Eclipse so you can edit scripts in Eclipse and automatically execute them in SketchUp.

View more content in this series

Tag this!

Date: 14 Apr 2009
Level: Intermediate
Activity: 2943 views

3-D modeling became a crucial task in a recent project of mine, and — desperate to find a design tool — I tried evaluation versions of AutoCAD, Blender, Maya, and SketchUp. As it turned out, SketchUp was by far the easiest to learn and the most fun to use. "It can't be this simple," I kept telling myself. But between the Google self-paced tutorials and the YouTube video demonstrations, I not only sprinted up the learning curve but thoroughly enjoyed completing the project.

Frequently used acronyms

API: Application programming interface
CVS: Concurrent Versions System
SVN: Subversion
UI: User interface

What made me even happier (I'm a programmer, not a graphic artist) was finding out that SketchUp executes command scripts, which means that I can automate tasks like adding labels to figures, assigning materials to surfaces, and drawing geometric shapes like parabolas and ellipses. SketchUp's API is based on the Ruby programming language, and, like SketchUp, it wasn't hard to learn. To expedite the coding process, I coded a custom Eclipse plug-in that communicates with SketchUp through the SketchUp Bridge.

This article provides a brief introduction to SketchUp, explains how the SketchUp Bridge works, and shows how to install the plug-in that connects Eclipse to SketchUp. The next in this article in this "3-D modeling with SketchUp and Eclipse" series will go into greater depth with regard to the SketchUp API and the types of designs you can create.

The SketchUp modeling tool

Like the Google site itself, Google SketchUp provides a great deal of capability beneath a simple interface. SketchUp's aim is to provide "3-D for Everybody," and it hits the mark: In five minutes, you can learn how to draw basic 2-D shapes and extrude them into 3-D figures. In half an hour, just by playing around, you can become proficient with every tool in the toolbar. Figure 1 illustrates the SketchUp UI. Though it looks like a modeling tool, SketchUp feels like a toy.

Figure 1. The SketchUp UI

Unlike Blender, SketchUp is not open source. Google's proprietary license allows you to use the tool for any legal purpose, and you can extend SketchUp with plug-ins, but no source code is available. SketchUp only runs on computers running Windows® or Apple Mac OS X, and two versions are available: a free version and a US$495 version called SketchUp Pro. SketchUp Pro provides professional layouts and styles, advanced file operations, and technical support. However, the free version still provides a ton of features, and before you continue reading, I strongly recommend that you visit the SketchUp site (see Resources) and download a copy.

Starting SketchUp

When you first launch SketchUp, you'll be asked which template you'd like to use. A template defines the measurement units and overall appearance of your design window. Twelve choices are available:

Simple Template (feet and inches) — Colors the x-y plane green, the positive-z region light blue
Simple Template (meters) — Colors the x-y plane green, the positive-z region light blue
Architectural Design (feet and inches) — Colors the x-y plane dark gray, the positive-z region light gray
Architectural Design (millimeters) — Colors the x-y plane dark gray, the positive-z region light gray
Google Earth Modeling (feet and inches) — Colors the x-y plane green, the positive-z region light blue
Google Earth Modeling (meters) — Colors the x-y plane green, the positive-z region light blue
Engineering (feet) — Colors the entire design region white
Engineering (meters) — Colors the entire design region white
Product Design and Woodworking (inches) — Colors the x-y plane dark gray, the positive-z region light gray
Product Design and Woodworking (millimeters) — Colors the x-y plane dark gray, the positive-z region light gray
Plan View (feet and inches) — Colors the entire design region white (starts with a 2-D view)
Plan View (millimeters) — Colors the entire design region white (starts with a 2-D view)

Except for the measurement units, there's no significant difference from one template to the next. I'm an engineering type, so I prefer the Engineering (meters) template.

When you've chosen a template, the SketchUp design window appears, and you see a series of lines that meet at a point called the origin. These lines define the coordinate system (x,y,z), and Figure 1 shows what they look like. The solid red line is the positive x-axis, and the dotted red line is the negative x-axis. The solid green line is the positive y-axis, and the dotted green line is the negative y-axis. The solid blue line is the positive z-axis, and the dotted blue line is the negative z-axis (xyz = RGB; get it?).

SketchUp drawing

This article is concerned with automating SketchUp, but first, you should have some idea of how to do things manually. Let's start by drawing two simple figures. As with Adobe® Photoshop® and Microsoft® Paint, SketchUp's drawing process involves selecting tools from a toolbar and clicking in the design window. Figure 2 shows the basic SketchUp toolbar.

Figure 2. The basic SketchUp toolbar

To start, click the Rectangle tool, which draws a solid rectangular surface. Create a rectangle by clicking on two points in the design window. As you'll see, the first shape of a design is always placed in the x-y plane. The result should look similar to Figure 3a.

Figure 3a. Simple SketchUp figures

The Push/Pull tool adds a third dimension to a face, and you use it to turn the rectangle into a box. Click the Push/Pull tool, click the rectangle, and move your mouse upward. A box appears in the SketchUp window, and its height changes with the position of the mouse. Click again to create a box similar to that shown in Figure 3b. The SketchUp term for creating a 3-D figure from a 2-D figure is called extrusion.

Next, draw a cylinder on top of the box. Click the Circle tool, then click in the center of the box's top surface. Move the mouse outward from the center and click again to form a circle similar to that shown in Figure 3c. Finally, click the Push/Pull tool again, move the mouse upward, and create the cylinder shown in Figure 3d. If you move the mouse downward, you can create a cylindrical hole in the box.

This basic lesson is very easy, but SketchUp can do much, much more. For thorough lessons, go to the SketchUp training site (see Resources) and work your way through the self-paced tutorials. When you're finished, watch the videos that cover intermediate and advanced topics, so you'll better understand the breadth of SketchUp's capabilities.

The SketchUp Ruby Console

Although SketchUp drawing is fun, I prefer to create designs in code. To see how this works, in SketchUp, click Window > Ruby Console to display a window with a command-line interface (CLI) at the bottom and an output window at the top. By entering code in this CLI, you can create and modify shapes in the design window. Before you start, remove any existing shapes by clicking the Selection tool, then pressing Ctrl+a followed by Delete. Then, at the Ruby Console's command line, type the following two commands:

face = Sketchup.active_model.entities.add_face [0,0,0], [9,0,0], [9,9,0], [0,9,0]


face.pushpull -9

These commands are written in Ruby, the only programming language SketchUp recognizes. Ruby is object-oriented, and the first command creates an object called face, which represents a rectangle in the current design. The second line creates a box by invoking the pushpull() method of the Face class. Figure 4 shows the output displayed in the console after both commands have been entered.

Figure 4. The SketchUp Ruby Console window

Now, if you look in the SketchUp design window, you'll see a square box (9x9x9) that touches the origin. To get a closer view, click the Zoom Extents tool. Using the SketchUp tools, you can move, scale, and rotate this figure as if it were a regular shape.

CLIs are fine, but we serious programmers place our code in files so we don't have to re-enter all of our commands. File access is accomplished through the load command, which reads in a Ruby script (*.rb) and tells SketchUp's Ruby interpreter to execute each of its commands. I've provided an example script called lathe.rb (see Downloads). This script creates a lathed shape using a different extrusion method than the Push/Pull mechanism described above. After you've downloaded this script, you can execute it with a command like the following (which assumes the script is in the C:\test folder):

load "C:/test/lathe.rb"

SketchUp now executes the commands in lathe.rb and displays the lathed shape in Figure 5.

Figure 5. Example lathed shape

The SketchUp Bridge

Thoughts on Ruby and Eclipse

The SketchUp API is based on Ruby, a relatively new programming language primarily used for enterprise computing (Ruby on Rails). I'd never programmed in Ruby before SketchUp, and I have no doubt many others are in the same position. It's not a difficult language to learn, and Ruby has many advantages over C, C++, and the Java™ programming language, such as its iterators and simple syntax. But make no mistake: It would have been easier for me if the creators of SketchUp had based their API on a more popular language.

Google didn't create SketchUp; it obtained the application when it acquired @Last Software. But because Google has so many Java programmers, it would be wonderful if they changed the API from Ruby to Java technology. Then it would become more popular in academia, and 3-D designers could use all the open source tools that Java technology provides. SketchUp wouldn't just be "3-D for Everybody" but also "3-D Coding for Everybody."

It would be even better if SketchUp's capabilities were implemented inside an Eclipse plug-in. Then, in addition to the design window, you could have all the resource navigators, debug/outline/console views, and CVS/SVN integration that Eclipse provides for. It wouldn't be terribly difficult: The Eclipse Graphical Editor Framework (GEF) can be built atop OpenGL just as SketchUp is. Then, SketchUp would really give AutoCAD some competition. If you need any volunteers, Google, shoot me an e-mail.

SketchUp allows you to load command scripts, but doesn't provide any type of script editor. Therefore, most script developers code scripts with a separate application and load them in the Ruby console window. We can do better. The SketchUp Bridge makes it possible to execute Ruby scripts outside SketchUp, which means you never have to enter commands in the console window. Later in this article, I explain how to access the SketchUp Bridge from Eclipse. For now, the first priority is to install the SketchUp Bridge files and see how they work.

Obtaining and installing the SketchUp Bridge

The SketchUp Bridge has been released by the mysterious folks at plugins.ro, whose laudable motto is, "Tools that make you happy." The license allows free access to the software for personal use. Commercial use requires permission from the author, whose name is given only as TBD. To obtain the software, visit the plugins.ro site (see Resources), and click the link for bridge.zip. After you've downloaded and extracted the archive, you'll find three important files:

bridge_load.rb — A Ruby script that serves as a plug-in for SketchUp
Bridge.so — A library of routines that the bridge_load plug-in accesses
SUB.exe — A Windows application that executes SketchUp scripts outside SketchUp

To install the SketchUp Bridge, place the first two files in the Plugins directory in your top-level SketchUp installation folder. On my system, this folder is C:\Program Files\Google\Google SketchUp 7\Plugins. Because bridge_load.rb is a Ruby script in the Plugins directory, it will be loaded automatically when SketchUp starts. This directory placement is what differentiates a SketchUp plug-in from a regular script.

Testing the bridge

Before you interface the SketchUp Bridge with Eclipse, you should verify that everything's working correctly:

Download the lathe.rb script (see Downloads) and place it in the same folder as the SUB.exe application that came with the SketchUp Bridge. The folder can be anywhere on your computer, not necessarily in SketchUp's Plugins directory.
Start SketchUp, or restart it if it was already running.
Open a Windows command prompt, and change to the directory containing SUB.exe and the lathe.rb script.
Type the command SUB lathe.rb.

The SUB application tells SketchUp to read the commands inside lathe.rb. SketchUp's Ruby interpreter executes the commands, and the result (shown in Figure 5) will be visible in the design window. This arrangement becomes particularly convenient when you have two monitors. Then, you can edit your script on one monitor and view the SketchUp design on the other.

Eclipse and the SketchUp Bridge

I'm a die-hard Eclipse fan, and when I need to write code in a new language, the first thing I look for is an Eclipse feature that provides the file support and editing capabilities that make me so ridiculously productive. The Ruby Development Toolset (RDT) used to be available, but it became part of Aptana's RadRails tool, which is now an add-on feature for Aptana Studio. You can download Aptana Studio and RadRails, but the installation process is long and complicated. Besides, if you just want a Ruby editor, downloading a 30-day evaluation version of the gigantic Aptana Studio isn't worth it.

Because I was dissatisfied with existing Ruby tools, I wrote my own simple Eclipse plug-in, which I temerariously call the SketchUp Software Development Kit, or SketchUp SDK. You can download it from Downloads. The plug-in provides two main features: a Ruby editor and a toolbar item that launches the SketchUp Bridge application. This section explains how to install the plug-in, and shows how scripts are edited and executed.

Note: This subject matter can be confusing, so let me clarify the terminology. In official Eclipse documentation, the term for an add-on is plug-in. In official SketchUp documentation, the word is plugin (no hyphen). The SketchUp API is a set of Ruby classes, modules, and methods that allow you to access a SketchUp design in code. The SketchUp SDK is an Eclipse plug-in that interfaces with SketchUp through the SketchUp Bridge, which contains a SketchUp plugin. The SketchUp SDK and the SketchUp Bridge are completely different, but the first relies on the second to interface with SketchUp from Eclipse.

Installing the SketchUp SDK

The SketchUp SDK is public domain, and because the SketchUp Bridge is Windows-only, the SDK only runs on Windows. After you've downloaded it, you need to perform four tasks:

Download the SketchUp Bridge archive, and place Bridge.so and bridge_load.rb in SketchUp's Plugins directory.
Extract sketchup_sdk.zip, and place SUB.exe (one of the SketchUp Bridge files) in the exe folder beneath the top-level org.dworks.susdk_1.0.0 folder.
Move the org.dworks.susdk_1.0.0 folder to the plugins folder in your top-level Eclipse installation.
Start or restart SketchUp and Eclipse.

The files and directories can be confusing, so let me explain the directory structure on my computer. I've installed Eclipse at C:\eclipse, and my top-level SketchUp directory is C:\Program Files\Google\Google SketchUp 7. Therefore, the SketchUp Bridge files — Bridge.so, bridge_load.rb, and SUB.exe — reside in the following locations:

C:\Program Files\Google\Google SketchUp 7\Plugins\Bridge.so
C:\Program Files\Google\Google SketchUp 7\Plugins\bridge_load.rb
C:\eclipse\plugins\org.dworks.susdk_1.0.0\exe\SUB.exe

Creating and executing scripts with the SketchUp SDK

If you've placed the SDK plug-in and bridge files in the correct locations, you're ready to start coding. The process of developing SketchUp scripts in Eclipse consists of three parts:

Creating a Ruby script (*.rb) in Eclipse
Adding SketchUp commands to the script
Clicking SUB on the toolbar to execute the script inside SketchUp

Figure 6 shows the editing environment.

Figure 6. The SketchUp SDK

If you're familiar with Eclipse, you probably don't need instructions on how to continue. But just in case, the following process will clarify the procedure:

In Eclipse, click File > New > Project.
Open the General folder, select Project, and click Next.
Type my_project as the name of the project, then click Finish.
In the Eclipse Package Explorer, right-click my_project, then click New > File.
Type my_script.rb as the name of the SketchUp script, then click Finish.
Paste the text from lathe.rb into the Eclipse editor, and save the script's content.
On the Eclipse toolbar, click SUB to access the SketchUp Bridge and send the script in the current editor to SketchUp. Alternatively, you can use the accelerator key, Ctrl+Shift+Space.
Open SketchUp, zoom in, and you'll see the same lathed figure as the one shown in Figure 5.

At this point, you should have the SketchUp-Eclipse environment set up, and you should have a basic understanding of SketchUp drawing. The next article will go into greater depth regarding the Ruby language and the code inside a SketchUp script.

Conclusion

Google's SketchUp application may be simple to use and understand, but this doesn't mean it lacks features. SketchUp provides a wealth of capabilities for modularizing your design and controlling every aspect of its appearance and geometry. One of SketchUp's most important features is its script interpreter, which executes Ruby scripts that create, modify, and delete aspects of a SketchUp design. But although SketchUp provides the script interpreter, it doesn't provide an editor; that's where Eclipse comes in.

Before you can interface Eclipse with SketchUp, you need to download the SketchUp Bridge. This application consists of three files that, if positioned correctly, allow you to execute SketchUp scripts outside SketchUp's console window. Next, you need to download and install the SketchUp SDK plug-in within Eclipse. The simple SDK makes it possible to edit scripts and execute them in SketchUp with a click of a button.

Downloads

Description	Name	Size	Download method
Eclipse plug-in that interfaces with SketchUp	os-eclipse-sketchup1_sdk.zip	29KB	HTTP
Ruby script to create a lathed shape	os-eclipse-sketchup1_lathe.zip	1KB	HTTP

Information about download methods

Resources

Learn

For tutorials and demonstration videos, visit Google's training site to learn more about how this incredible tool works.
For more information about the Ruby programming language, 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.

Discuss

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.

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=Open source

ArticleID=380719

ArticleTitle=3-D modeling with SketchUp and Eclipse, Part 1: Creating the bridge between SketchUp and Eclipse

publish-date=04142009

author1-email=mattscar@yahoo.com

author1-email-cc=