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.
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.
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?).
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]
These commands are written in Ruby, the only programming language SketchUp
recognizes. Ruby is object-oriented, and the first command creates an
face, which represents a
rectangle in the current design. The second line creates a box by invoking
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
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):
SketchUp now executes the commands in lathe.rb and displays the lathed shape in Figure 5.
Figure 5. Example lathed shape
The SketchUp Bridge
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
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:
- Download the SketchUp Bridge archive, and place Bridge.so and bridge_load.rb in SketchUp's Plugins directory.
- 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.
- 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
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
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.
my_projectas the name of the project, then click Finish.
- In the Eclipse Package Explorer, right-click my_project, then click New > File.
my_script.rbas 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.
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.
|Eclipse plug-in that interfaces with SketchUp||os-eclipse-sketchup1_ide.zip||29KB|
|Ruby script to create a lathed shape||os-eclipse-sketchup1_lathe.zip||1KB|
- 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.
- 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.