Frequently Asked Questions (FAQ)
Basic Questions
What is SketchUp?
SketchUp if Google's easy-to-use 3d modeling software. It is available in both Free and Pro Versions from the
http://sketchup.google.com. It is used worldwide for drawing 3d objects of all kinds. You can find thousands of examples of what you can do with SketchUp at the
Google 3d Warehouse.
What is Ruby?
Ruby is "an interpreted scripting language for quick and easy object-oriented programming." You can learn more at
http://www.ruby-lang.org/. Most importantly for us, it's a language that SketchUp can understand via its SketchUp Ruby API.
What is the SketchUp Ruby API?
The SketchUp Ruby API (Application Programmer's Interface) is a way that Ruby programmers can extend the capabilities of SketchUp to meet their needs. By creating a script (aka a text file) and placing it in SketchUp's
plugins directory, you can make SketchUp do all kinds of things:
- Create custom drawing tools, like a tool for creating windows.
- Attach attributes to drawing elements such as cost, supplier, etc.
- Read attributes to generate reports, cut lists, or bills of material.
- Automate common tasks like generating scenes from a set of rotations.
- Animate stuff, from drawing elements to camera position.
- Make games inside SketchUp by combining these activities.
- ...and much more.
What is a Ruby Plugin?
In the SketchUp world, "plugins" is just another term for "scripts," which is another word for "rubies." You'll see these terms used interchangeably. Scripts are text files with a .rb (ruby) or .rbs (
scrambled ruby) extension that contain Ruby programming code.
What is a SketchUp Extension?
A SketchUp Extension is like any other Ruby script, except for the fact
that you make a
few extra code calls
to tell SketchUp that it's an "extension," which means that users can easily
turn it on or off by clicking a checkbox under the SketchUp Preferences >
Extensions menu. Extensions are a little more work to code, but they make it
easier for end users to manage all of their rubies.
|
Ruby Extensions are scripts
that can be turned on or off
via your preferences window.
|
Okay then what is a Ruby Extension Module?
A Ruby Extension Module is a compiled library that can talk to SketchUp via
the Ruby API, which can give you greater performance and access to most
anything that your computer can do. A Google search for
Ruby
Extension is a great place to start learning more.
Do I need SketchUp Pro to run or create Ruby Scripts?
No. The full Ruby API is included in both SketchUp Free and SketchUp Pro.
So how do I write a plugin, in 4 bullets or less?
- Use your favorite text editor to create a file (like "myplugin.rb")
- Put some ruby commands into that file (like "UI.messagebox('hello world')")
- Save the file into SketchUp's plugins directory.
- Restart SketchUp to load your new plugin.
Click here for a
detailed Hello World tutorial where you'll create and install your first script.
Where can I find SketchUp Ruby Plugins?
You can find a number of free and commercial scripts at:
How do I install a single-file Ruby Plugin?
The simplest kind of plugin is a single .rb script file. To install such a script, copy the file into your /Plugins folder then restart SketchUp.
You can read more about this on our loading ruby scripts page.
How do I install a multiple-file Ruby Plugin?
Some ruby plugins are made up of several files, including .rb file, .html files, etc. These are typically installed by copying the entire set of files and folders into your Plugins directory. Look for a readme.txt file or other instructions from the plugin author. You can read more on our
loading ruby scripts page.
Where can I find other SketchUp Ruby programmers to network with?
The official group can be found at
http://groups.google.com/group/google-sketchup-developers. There is also a wonderful Ruby community at
http://www.sketchucation.com.
What is the SketchUp Ruby Console?
The
SketchUp Ruby Console is a small dialog that you can display using the Window > Ruby Console menu item. The Console provides direct access to SketchUp Ruby Interpreter. There is an input box where you can type Ruby commands and an output window where you can view debugging output.
I'm having trouble with a Ruby plugin. What do I do?
First, open the Ruby Console inside SketchUp to ascertain if there are any obvious errors. You can open the Ruby Console under Window > Ruby Console. Then enter Ruby commands to interact with your plugin and watch the console for error messages.
Once you've done that, the best course of action is to contact the plugin author. Check the plugin for a readme.txt or similar file, or look inside the .rb file itself, to see if they included contact information. If that fails, try visiting one of the
user forums and asking for help there.
I think I need a Ruby script, but don't program. What do I do?
If you'd like to hire someone, there are lots of talented Ruby programmers out there who do contract work. Visit the
google group or
Ruby forum on Sketchucation.com and make a post. In general, the more detail you can provide in the post about your needs the more interest you will see from the community.
We also have some suggestions on our Getting Started page if you are not a programmer but would like to learn.
Advanced Questions
If I make changes to my script, how do I reload it without restarting SketchUp?
Open the SketchUp Ruby Console by selecting Window > Ruby Console from the menu. Let's say the script is called HelloWorld.rb. Simply type in "load 'HelloWorld.rb' " into the input box and SketchUp will reload and execute the script.
As a plugin author, how can I prevent people from stealing my script?
Use the free Ruby Scrambler to obfuscate your code. Read more under our
distributing your script article.
I don't have a (Mac/PC), how can I test on both platforms?
The best practice is to test thoroughly on both platforms. You might try asking on the
google group or
Ruby forum on Sketchucation.com if anyone would be willing to help you test.
What are the differences between the Mac and PC when it comes to the Ruby API?
The biggest difference between the two platforms are the WebDialogs. On the PC, the embedded browser is Internet Explorer, and on the Mac it's Safari. See the
WebDialog documentation for details about all of the differences. if you're not using the WebDialogs for anything, then you don't have to worry about it.
Another difference is the fact that the Mac supports "MDI" (Multiple Document Interface), meaning there can be more than one SketchUp model open at a time under the same SketchUp process. This can cause Ruby scripting challenges if your code is doing something with an entity only to have the user change the active model out from under you. There's no easy answer for how to handle all of the potential problems with this... it's probably enough for you to be aware of it and be sure to test what happens when a Mac user changes the active window while your script is active.
Finally, there is a difference in the way that the Mac boots up SketchUp that you should be cautious about: there is no Sketchup.active_model when the Ruby scripts are first loaded. So if your script is making changes to the active_model at load time, it will not work on the Mac. The answer? Ensure code that references the active model is part of a UI event handler, responding to the user
selecting a tool or a
menu item. You can also use an
AppObserver to get a callback whenever a new model is opened, at which point it's safe to talk to the active_model.
How can I detect if my plugin is running on the Mac vs. PC?
You can get OS information from Object::RUBY_PLATFORM.
Here's a commonly used snippet of code:
PLATFORM = (Object::RUBY_PLATFORM =~ /mswin/i) ? :windows : ((Object::RUBY_PLATFORM =~ /darwin/i) ? :mac : :other)
Are there any debugging tools available for Ruby?
Not that are commonly used with SketchUp. Debugging Ruby is a challenge that typically requires a lot of puts() statements to print things to the Ruby console and watch what's going on, or even using Ruby's file access capabilities to write to log files. If you're really stuck on something, post your problem to the
google group or
Ruby forum on Sketchucation.com. We're all happy to help.
My script is slow. How can I improve performance?
Here are some ideas:
- Optimize your ruby code to do as few operations as possible, especially geometry manipulation as these can have high overhead. SketchUp has to not only create the geometry, but also check to see if the new stuff needs to merge in any way with the existing stuff. SketchUp is a wonderful modeling tool because it is very smart about merging geometry together when they touch, but this can also slow you down on large models.
- Comment out all of those puts() statements that are writing debugging information to the Ruby console. Refreshing that thing takes a while. Here's a tip: create your own method like this one, and call it instead of puts(). Then you can turn debugging output on or off with a simple switch:
def debug_puts(message)
if @show_debug_messages == true
puts(message)
end
end
- Wrap your code in a Model.start_operation with the go_faster flag set to true.
- Use a compiled Ruby extension module to do the work in compiled code.
What parts of Ruby comes with SketchUp?
Only the minimal "core" Ruby modules come with SketchUp on the PC. On the Mac, the full standard Ruby install is included with the OS.
I need a Ruby module (such as CGI) that doesn't come with SketchUp. What do I do?
You could either require that your plugin users install the latest version of Ruby on their computer (it comes standard on the Mac, by the way) or you could distribute the needed .rb files in a subdirectory that you add to the /Plugins directory when they install your script.
How can I make a nice point and click installer for my plugin?
There are a number of
installer creation tools on the internet. For the PC,
Spoon Installer is a popular option.
Where can I find documentation on all of the things Ruby can do in general?
Visit the main ruby site at
http://www.ruby-lang.org/.
Can I use the Ruby API to generate a Bill of Materials from a model?
The short answer: yes.
The long answer: a bill of materials is a complex thing that is different for each industry and user group. Since SketchUp is a surface modeler that doesn't necessarily know that the box you're drawing is, say, a piece of lumber, there could be a fair amount of work that your script would need to do to get the results that you want. But that's why it's a generic programming API: you can do whatever you want with it.
Can I run SketchUp on the Web?
No. SketchUp is a desktop application. SketchUp's WebDialog object does allow you to integrate web content with SketchUp. See the
WebDialog class for more details.
Can my plugin run off the Web?
Sort of. SketchUp's WebDialog class allows your plugin to open an embedded web browser inside of SketchUp and display a website (or a user interface hosted on a website.) With some javascript coding, it is possible for your website to then talk to the Ruby API (subject to certain security considerations). See the
WebDialog class for more details.
If my plugin works in SketchUp 7, will it work in SketchUp 6 and earlier?
Not necessarily. See the
release notes for the API features that have been added in each version. If you use methods that are only around in the latest version, then expect that a certain percentage of your users will have problems. The good news is that you can detect the user's version in your plugin and react accordingly:
# You can have this sort of code in the initialization routine of your plugin.
version_required = 7.0
if (Sketchup.version.to_f < version_required)
UI.messagebox("You must have Sketchup " + version_required.to_s +
" to run this plugin. Visit sketchup.google.com to upgrade.")
return
end
How do I detect the version of SketchUp a user is running?
version_as_number = Sketchup.version.to_f
How can I animate things using Ruby?
Use a timer to call a bit of Ruby every X milliseconds. Learn more on the Blog when you
Animate Yo Cheese! You can also investigate the animate.rb
example file.
I found a bug in the API. What do I do?
You can help us best by first searching the
Google SketchUp Developers group to see if your bug has already been reported in the forums. You might also want to search on
Sketchucation. The SketchUp team watches and responds to bug reports on both of these forums.
If you can't find a reference to your bug, please post it along with any information you can provide that might help us reproduce your bug.
I have a feature request for the API. What do I do?
We recommend posting feature requests to the
Google SketchUp Developers group. You might also want to make a post to the Ruby API forum on Sketchucation. There is a
sticky post there specifically for API requests.
How can I add my own menu item to SketchUp?
See the
Menu class for detailed examples of creating your own Tool.
Is Bryce a real person?
Yes. Bryce is a product manager who has been with the SketchUp team "forever." (
Bryce, by the way, is the person component inside the architectural templates in SketchUp 6.)
Is Sang a real person?
Yes. Sang is a software engineer on the SketchUp team. (
Sang, by the way, is the person component inside the architectural templates in SketchUp 7.)
|
