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

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.

Matthew Scarpino, 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).


developerWorks Contributing author
        level

14 April 2009

Also available in Russian Japanese Portuguese

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
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
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
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
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
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:

  1. 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.
  2. Start SketchUp, or restart it if it was already running.
  3. Open a Windows command prompt, and change to the directory containing SUB.exe and the lathe.rb script.
  4. 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 Integrated Development Environment, or SketchUp IDE. 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 IDE is an Eclipse plug-in that interfaces with SketchUp through the SketchUp Bridge, which contains a SketchUp plugin. The SketchUp IDE and the SketchUp Bridge are completely different, but the first relies on the second to interface with SketchUp from Eclipse.

Installing the SketchUp IDE

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

  1. Download the SketchUp Bridge archive, and place Bridge.so and bridge_load.rb in SketchUp's Plugins directory.
  2. Extract sketchup_ide.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.
  3. Move the org.dworks.susdk_1.0.0 folder to the plugins folder in your top-level Eclipse installation.
  4. 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 IDE

If you've placed the IDE 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 IDE
The SketchUp IDE

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:

  1. In Eclipse, click File > New > Project.
  2. Open the General folder, select Project, and click Next.
  3. Type my_project as the name of the project, then click Finish.
  4. In the Eclipse Package Explorer, right-click my_project, then click New > File.
  5. Type my_script.rb as the name of the SketchUp script, then click Finish.
  6. Paste the text from lathe.rb into the Eclipse editor, and save the script's content.
  7. 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.
  8. 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 IDE plug-in within Eclipse. The simple IDE makes it possible to edit scripts and execute them in SketchUp with a click of a button.


Downloads

DescriptionNameSize
Eclipse plug-in that interfaces with SketchUpos-eclipse-sketchup1_ide.zip29KB
Ruby script to create a lathed shapeos-eclipse-sketchup1_lathe.zip1KB

Resources

Learn

Get products and technologies

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.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


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