Google SketchUp API Blog

SketchUp Ruby API site updated for SketchUp 7.1

2009-11-02T10:45:00.000-08:00

SketchUp 7.1 launched back in September. Last week, we updated the SketchUp ruby API Site with all the changes that have been made since the release of Sketchup 7.0 (Nov 2008). This includes documentation fixes and updates for several new methods. For all the details check out the API release notes.

We would also like to say "Thanks!!" to the SketchUcation community and the guys over at Smustard.com for sending us Ruby documentation fixes. SketchUp's amazing developer community continues to be one of the best "features" of the Ruby API.

~Bryce Stout
Product Manager

Dynamic Components that react to scene (aka page) changes

2009-07-23T16:18:00.000-07:00

Have you ever wanted to have a Dynamic Component that reacts to Scene changes?

Well, this blogpost tells you how to write one (thanks to John Clemens for the idea).

First of all, you need a mechanism to detect a scene change. After some struggles with using the PagesObserver, I decided to use the FrameChangeObserver.

The add_frame_change_observer method is used to add a new FrameChangeObserver that is called with each frame of an animation. This means the end user has clicked on a Scene tab (aka Page) inside SketchUp and the camera is animating to that scene. Moreover, it provides you with a percent_done variable and fromPage and toPage variables which allow you to have finer feedback over the state of the animation.

The other challenge is that we need to find the DC that will react to the scene change. This can be accomplished by traversing the model entities and examining all the component instances that have a “dynamic_attributes” dictionary attached to them; those are the dynamic components in the model. Once we have a way to find all the dynamic components, it is just a matter of detecting which ones we want to influence on a scene change. For that, we add a SCENE_CHANGE Boolean (true or false values only) attribute to the top level attributes of our DC to indicate whether or not we want that DC to change. Then, we add a SCENE_TRIGGER attribute that contains an index that is affected by each scene change and that changes between 1 and 4 (this can be customized to be anything you want). This can then can be used to drive changes in the DC.

To see this in action, put the attached script in the Tools or Plugins folder of SketchUp, open the attached model, change the scene, and ta-dah the magic begins. You will notice that one of the two components does not change, the reason being that the attribute SCENE_CHANGE for that component is set to 'false'. Change it to 'true' and you will see it changing.

It is important to notice that there are several observers available from Ruby (e.g ToolsObserver, SelectionObserver, etc.) and any of them can be used to trigger changes in dynamic components using the same strategy I used in the attached script. DC can be made to change according to which tool is currently active, or depending on the currently selected material.

Download the example model here.

Code snippet below

----------------------------------------------------------------

# Copyright 2005-2008, Google, Inc.

# Permission to use, copy, modify, and distribute this software for
# any purpose and without fee is hereby granted, provided that the above
# copyright notice appear in all copies.

# THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
# IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
#

# This code snippets allows you to have Dynamic Components
# that modify themselves based on a Scene Change
#
# They need to have at the top level the following attributes
# "scene_change" a boolean value that if true force the DC to react to scene changes
# and if false has the DC ignore the scene change
# and
# "scene_trigger" which is the index that is incremented every time there is a scene change and
# it is used to change attributes for the DC.
#
#
# Author: Simone Nicolo

require 'sketchup.rb'

# Define the Frame Change Observer which is documented in the Pages class.
class FrameChangeObserver

def initialize
# @current page is used to make sure that the observer is only triggered by page changes
# This is to workaround the PC bug that does not correctly populate the fromPage variable in the
# callback to frameChange.
@current_page = Sketchup.active_model.pages.selected_page
end

# Callback triggered by the Frame change observer.
# fromPage is populated with the page we were coming from, toPage is
# populated with the page we were transitioning to
# and percent done contains the percentage of the transition that
# has completed.
def frameChange(fromPage, toPage, percent_done)
# If there has been a page change and it has completed
if (not toPage.nil? and percent_done == 1) then
if @current_page != toPage then
#update the current page
@current_page = toPage
#find the DCs that need redrawing, and redraw them.
find_dc_for_redraw
end
end
end

# This function finds all the DC's that need to be redrawn based on a scene transition and
# on the boolean scene_change attribute if scene_change is true, change and redraw
# the DC on a scene transition, if it is false do not change or redraw the DC.
def find_dc_for_redraw
entities_list = Sketchup.active_model.entities
if entities_list != []
# For all the entities in the model
entities_list.each do |item|
type = item.typename
case type
# Find the Dynamic Component instances
when "ComponentInstance"
if not item.attribute_dictionaries.nil?
attributes = item.attribute_dictionaries[DICTIONARY_NAME]
# If they have a scene_change attribute that contains true
if (not attributes.nil? and attributes[SCENE_CHANGE] == 1.to_s)
# Increment the scene_trigger attribute.
# Here we are allowing the scene trigger attributes to only have the values
# 1, 2, 3, and 4.
attributes[SCENE_TRIGGER] = (((attributes[SCENE_TRIGGER].to_i+1)%5)).to_s
if attributes[SCENE_TRIGGER] == "0" then
attributes[SCENE_TRIGGER] = 1.to_s
end
# Redraw the DC using the $dc_observers global variable.
$dc_observers.get_latest_class.redraw_with_undo(item)
end
end
end
end
else
UI.messagebox("There are no entities in this model!")
end
end

end

if not file_loaded? 'scenes.rb'
# Useful constants
# Dynamic Components dictionary name
DICTIONARY_NAME = "dynamic_attributes"
# Boolean attribute that turns on and off the reaction to a scene change for the DC
SCENE_CHANGE = "scene_change"
# Index attribute for the DC that is used to drive changes in the DC.
SCENE_TRIGGER = "scene_trigger"
# Attach the frame chage observer to the global Pages object.
id = Sketchup::Pages.add_frame_change_observer(FrameChangeObserver.new)
file_loaded 'scenes.rb'
end

Champion the 3D Web using COLLADA Contest

2009-05-07T08:22:00.001-07:00

Our friends over at the Khronos group are holding a Champion the 3D Web using COLLADA Contest. They're looking for the best 3D models, avatars, worlds, or simulations created using COLLADA. Prizes include cash awards and opportunities at a future Immersive Education Initiative in-world (virtual) events. The contest will run through July 15, 2009. Winners will be announced at Siggraph this year in New Orleans. The contest is sponsored by the Khronos Group and the Media Grid Immersive Education Initiative. Please check out the contest site for full details.

Using SketchUp to enter the contest
SketchUp can be used to create models for this contest. SketchUp Pro and the Pro Evaluation both export COLLADA (DAE) files directly. The free version of SketchUp can export Google Earth (KMZ) files which contain a COLLADA model. To extract a COLLADA model from a KMZ file follow these steps:

Export your SketchUp model to KMZ.
Change the file extension from ".kmz" to ".zip".
Double-click on the ZIP file.
Double-click on the "models" folder.
Locate the DAE file. Copy and paste this file to your Desktop.
Check your file's appearance in a COLLADA viewer like Swirl X3D Viewer©
Submit your model to the contest.

Good Luck!
Bryce Stout
Product Manager
Google

Ruby API Objects diagram

2009-04-17T09:15:00.000-07:00

Posted by Simone Nicolo, Google SketchUp team.

Have you ever wondered how the various classes are organized in the ruby API?
Well, I recently created a diagram to show the objects hierarchy for the SketchUp Ruby API.

It can be found here and it provides an easy way to visualize relationships between SU API's various objects.

Below are some examples of ways in which the diagram can be used:

Example 1
In the diagram, it is evident that the Entity class has several subclasses which all inherit the Entity class methods. For example, the Face class can add an EntityObserver to its instances just by taking advantage of the inherited methods from the Entity class.

Example 2
It is also visually clear that I can get handles to different entities using Ruby. For example, if I want to obtain a handle to my current model, I can do so using Sketchup.active_model or Entity.model. The Entity.model method will work on any class that inherits from Entity.

Example 3
I can clearly visualize which classes have observers and which do not. For example, I can easily see that the View class has its own observer, while the camera class does not.

To keep it as simple as possible, some classes were not included in the diagram.

Hopefully this will help you better visualize the organization of the Ruby API elements.

Simone.

SketchUp API Updates

2009-04-01T09:33:00.001-07:00

Updated Ruby API Documentation

The guys over at the SketchUcation Community Forums have been submitting documentation corrections to us and we just pushed a bunch of updates to our Ruby API Site . Thanks to everyone who's been helping us improve our docs! If you find other typos or problems please join the thread on SketchUcation or post to our ruby group.

New Ruby Tutorial

Check out our new tutorial on Attribute Reporting to learn how to read attribute data from entities in your models.

New SDK Package

We recently repackaged the SDK to make it a bit easier to use. Improvements include:

- Reorganized folders to make them more understandable
- New GettingStarted.html intro to help get folks headed down the right path
- Updated SkpReader and SkpWriter documentation
- Updated SkpToXml example to compile on the PC

We also removed Client Warehouse SDK from the package. If you need support on this please post your contact info to the SDK support group.

There were no changes to the headers or binaries so there are no code fixes with this release. Please download the latest package at - http://code.google.com/apis/sketchup/docs/downloadsdksubmit.html

Bryce Stout
Product Manager
Google

Deleting Unnecessary Edges

2009-03-12T10:19:00.000-07:00

Posted by Sandra Winstead, SketchUp Team

Have you ever opened a SketchUp file that you didn’t create, or imported a model from another application, and found that it has hundreds of needless hidden or softened lines separating coplanar faces? Wish you could get rid of them with a simple ruby script? Now you can!

First, set up a few variables:

def variables
  @group_list = []
  @component_list = []
  @delete_these = []
  @model_list = Sketchup.active_model.entities
end

Then write a method that determines if an edge is 1) hidden or softened, and 2) bordered by two co-planar faces. If the edge meets each of those requirements, it is added to @delete_these list.

def delete_soft_lines(e)
  # Determine if the edge is soft or hidden, and if it is bordered by 
  # two faces.
  if ((e.soft? and e.faces.size == 2) or (e.hidden? and e.faces.size == 2))
    # Determine if the two bordering faces are coplanar.
    # Note: This will only catch cases where the front faces are pointing 
    # in the same direction.
    if (e.faces[0].normal.dot(e.faces[1].normal) > 0.999999999)
      # Add the edge to the list of entities that will be deleted.
      @delete_these.push(e)
    end
  end
end

Now create a method to find all the edges in the model, including edges that are embedded in groups and components:

def traverse_model_entities
  # @model_list will not be empty until all of the groups, components 
  # and edges have been traversed.
  while @model_list != []
    @model_list.each do |item|
      # Determine if the entity is an edge, group, or component.
      type = item.typename
      case type
        when "Edge"
          # Determine if the edge should be deleted, and add it to the 
          # @delete_these list.
          delete_soft_lines(item)
        when "Group"
          # Add each of the entities in the group into the group_list
          # array.
          item.entities.each do |entity|
            @group_list.push entity
          end
        when "ComponentInstance"
          # .entities can be called on a Component Definition, but not on
          # a Component Instance.
          # Use the .definition method to access the Component Definition
          # that the instance belongs to.
          item.definition.entities.each do |entity|
            # Add each of the entities in the component into the
            # component_list array.
            @component_list.push entity
          end
      end
    end
    # Update the @model_list so it contains only the entities that were 
    # embedded in groups or components. These entities haven't been
    # counted yet.
    @model_list = @group_list + @component_list
    # Clear out the group and component lists so they're ready for the
    # next level of sub-groups/components.
    @group_list = []
    @component_list =[]
  end
  # The edges that need to be deleted have all been added to the
  # @delete_these list, so erase those entities from the 
  # active SketchUp model.
  Sketchup.active_model.entities.erase_entities(@delete_these)
end

Finally, add a “Delete unnecessary edges” item to Tools menu, and pop a dialog letting you know the edges were deleted:

def delete_edges
  variables
  traverse_model_entities
  UI.messagebox("Edges deleted.")
end

UI.menu("Tools").add_item("Delete unnecessary edges") {delete_edges}

Google I/O 2009

2009-03-06T13:01:00.000-08:00

The Google I/O Developer Conference is May 28th and 27th in San Francisco, CA. Members of the SketchUp team will be presenting in the What you don't know about Geo APIs can't hurt you session and will also be available during Office Hours. Hope to see you there!

Posted by Bryce Stout, Product Manager

SketchUp Importers

2009-02-23T17:01:00.000-08:00

Posted by Sang Ahn, SketchUp Team

There's a lot of 3D content out there, and we understand that a lot of it is not in the SketchUp file format. But, if you can read the content, you can use the Ruby Importer plugin API to import it into SketchUp.

It's easy to write and use your own Ruby importers in SketchUp. Just follow these steps:

1. Define a class with the plugin API methods.
2. Register an object of the class with SketchUp.
3. Recover from Mardi Gras festivities (may not be applicable).

An importer class must have the following methods:

def description
  # Returns a brief description of your importer plugin.
end

def file_extension
  # Returns the file extension of the file format your
  # importer can read (e.g. fbx, dae, etc.)
end

def supports_options?
  # Returns true if your plugin supports import options.
end

def do_options
  # Presents the import options dialog panel to the user.
end

def id
  # Returns the id string of your importer.
end

def load_file(file_name, show_summary)
  # Reads the contents of location on disk specified
  # by file_name.
  # Shows the summary dialog panel if show_summary is true.
  # Returns 0 on success, returns 1 on failure.
  0
end

Once you have defined your importer class, register your importer with SketchUp:


Sketchup.register_importer MyImporter.new

Now your importer plugin will be available when you select the Import item under the File menu of SketchUp. The Ruby Importer capability is available in both SketchUp Free and Pro. Now go forth and import.

The SketchUp 7 SDK is now available

2009-01-21T09:51:00.000-08:00

Posted by Bryce Stout, SketchUp Team

We have recently updated the SketchUp SDK for folks who need read and/or write SketchUp 7 files. It is available on http://code.google.com/apis/sketchup/docs/downloadsdksubmit.html. If you have feedback or questions, please post your questions or suggestions to the SketchUp SDK Group. If you would like to be notified about future SDK updates and news, please subscribe to this blog, if you haven't already.

Happy SketchUp Developing!
Bryce Stout
Product Manager

Playing Sounds in SketchUp

2009-01-07T16:02:00.000-08:00

Posted by Scott Lininger, SketchUp Team

This week I'd like to talk about a much-maligned feature of the SketchUp Ruby API... UI.play_sound. Why would you ever want to play sound via the Ruby API? Glad you asked!

Besides the obvious desire to listen to Marvin Gaye while drawing your skatepark, you could enhance a scene tour with sound effects that match the location where your camera is located. It puts the multi in multimedia. Sounds fun, right? Let's try it.

Step 1: Get a Zoo With some Scenes

For this exercise, we're going to need a model with some Scene tabs. Luckily I have just the zoo. Click here to download a ZIP file with everything you need to follow this example.

Once you get it, unzip everything to your SketchUp/Plugins/ directory. It contains four files:

zoo.skp - a model of the world's lamest zoo
zoo.rb - the code that we're about to talk about
zoo_lion.wav - what the lion says
zoo_elephant.wav - what the elephant says
zoo_sang.wav - what Sang says

Step 2: Don't Feed the Animals

Once everything is in your /Plugins/ directory, open the zoo.skp file
and click the Scene tabs. Turn up the volume. You should hear a sound
effect that the Ruby API plays at each scene stop.

Step 3: Explore the Code

Here's the entire script. It shows using a Page Observer to capture
each frame of our scene animations. It watches the callback parameter
percent_done to figure out when the animation is complete, and then
it plays the sound.

# Create a class that will "observe" frame changes.
class ZooFrameObserver <  Sketchup::ViewObserver

  def frameChange(from_page, to_page, percent_done)
    if percent_done == 1.0
      if to_page == Sketchup.active_model.pages[0]
        UI.play_sound("Plugins/zoo_lion.wav")
      elsif to_page == Sketchup.active_model.pages[1]
        UI.play_sound("Plugins/zoo_elephant.wav")
      elsif to_page == Sketchup.active_model.pages[2]
        UI.play_sound("Plugins/zoo_sang.wav")
      end
     end
  end

end

# Attach our observer.
Sketchup::Pages.add_frame_change_observer(ZooFrameObserver.new)

I look forward to the day when every ruby script will play sounds with each interaction. I also like the blink tag. Huzzah!

What's New in SketchUp 7

2008-11-13T13:33:00.000-08:00

Posted by Scott Lininger, SketchUp Team

SketchUp 7 contains several improvements to the Ruby API. Here's a quick tour of the best changes.

Improve your script's performance!
Ability to perform faster inside start_operation transactions.
go_faster = true
model.start_operation operation_name, go_faster

Results from some real world tests, once the go_faster boolean was added:

Intersect overlaps with 500 overlapping squares
28.4 seconds vs. 26.3 (~92% as long)

Make faces with 500 faceless cubes
21.7 seconds vs. 14.5 (~66% as long)

Windowizer 3.0 with Four 20'x20' windows, 12x12
16.1 seconds vs. 7.0 seconds (~43% as as long)

Windowizer 4.0 with Ten 5'x5' windows, 6x6
22.6 seconds vs 8.7 seconds (~38% as long)
Leverage improved Web Dialogs
Addition of min/max widths.
WebDialog.min_width=100
WebDialog.max_width=300
WebDialog.min_height=500
WebDialog.max_height=600

Fixed Mac support for WebDialogs execute_script
WebDialog.execute_script('alert("Bug is Fixed!")');

New full_security mode for webdialogs (disables plugins and remote links)
WebDialog.set_full_security

Ability to hide home/next/back navigation icons on the Mac
WebDialog.navigation_buttons_enabled=true

Cleaner, hash-based syntax for initializing
my_dialog = WebDialog.new(my_settings_hash)
Control Scale Tool handles on your components
Your script can now control which scale tool handles appear
# Disable the green and red-axes handles
# by setting bits 1 and 2 to 1.
behavior = my_component_definition.behavior
behavior.no_scale_mask = (1 << 1) + (1 << 2)
Load Definitions from the Web, or save to disk
Ability to download a definition from URL
model.definitions.load_from_url(url, download_handler)

Ability to Save components to disk from the API
my_definition.save_as(path)
Know more about what your users are doing
New methods for detecting "Component Edit" mode
users_current_edit = model.active_path
edit_mode_transform = model.edit_transform

Easily determine if they're running in licensed Pro
is_licensed_pro = Sketchup.is_pro?

New "model level" callbacks in ModelObserver
def onActivePathChanged(model) { # Detect edit mode }
def onPlaceComponent(instance) { # Detect placements }
def onExplode(model) { # Detect group/component explode }
def onBeforeComponentSaveAs(instance) { # Add data on save as }
def onAfterComponentSaveAs(instance) { # Then clean up }

Detect if they've turned off your extension via the AppObserver
def onUnloadExtension(extension_name)
Delete your scenes via the API
my_page.erase
Keep SketchUp in Synch
UI.refresh_inspectors # force complete UI update
my_definition.refresh_thumbnail # force thumb update
my_definition.invalidate_bounds # force bb update
Measure your groups regardless of their transform
untransformed_bb = my_group.local_bounds
Use middle mouse button in your custom tools
def onMButtonDown(flags, x, y, view) { # now works! }
def onMButtonUp(flags, x, y, view) { # now works! }
Send ruby console output to the standard out
If you start up SketchUp from the command line, you can pipe to standard error and see ruby puts statements appear for you.
Sketchup.exe > myRubyLog.txt
and your users will benefit from numerous stability fixes!

Detailed documentation is coming soon... stay tuned!

Storing and Retrieving with AttributeDictionary

2008-11-05T09:38:00.000-08:00

Posted by Mason Thrall, 3D Data Specialist

The AttributeDictionary class allows you to store information into a SketchUp Entity. A good way to demonstrate this is to store camera settings into an object in an AttributeDictionary, then activate a context menu on the Entity to get these camera parameters and return to the same camera. This is also a great way to visualize important views in 3D space.

Our first method definition will create the camera geometry and put it into a group Entity. Then we will create an AttributeDictionary in the group and store the camera settings into the AttributeDictionary.

We will start by getting the current camera parameters and storing them into variables:

def reveal_view

   m=Sketchup.active_model
   m.start_operation("reveal view")
   ents=m.entities
   view=m.active_view
   cam=view.camera
   up=cam.up
   target=cam.target
   persp=cam.perspective?
   fov=cam.fov
   eye=cam.eye
   focus_ray=Geom::Vector3d.new(eye,target)
   eye_axes=focus_ray.axes

Next, we'll make a simple representation of the camera, using the stored camera settings to determine the geometry,

   target_pointer = ents.add_cline(eye,target)
   eye_point = ents.add_cpoint(eye)
   target_point = ents.add_cpoint(target)
   circle = ents.add_circle(eye, focus_ray, 20, 8)

and store them into a group. For better organization, create a "cameras" layer and put the group into this layer. Also, be sure to lock the group, so the camera geometry can't move.

   camera_geom = []
   camera_geom.push(target_pointer,eye_point,target_point,circle)
   camera_geom.flatten!
   cam_group=ents.add_group(camera_geom)
   cam_group.name="camera"
   cam_layer=m.layers.add("cameras")
   cam_group.layer=cam_layer
   cam_group.locked=true

We will then be storing the camera settings into the AttributeDictionary called "is_a_camera".
Create the AttributeDictionary in the cam_group Entity:

   is_camera=cam_group.attribute_dictionary("is_a_camera", true)

The "true" indicates that the AttributeDictionary doesn't yet exist and needs to be created. AttributeDictionary objects store arbitrary amounts of key/value pairs. Add key/value pairs to AttributeDictionary for the camera settings,

   is_camera["cam"]=cam
   is_camera["up"]=up
   is_camera["target"]=target
   is_camera["persp"]=persp
   is_camera["fov"]=fov
   is_camera["eye"]=eye
   is_camera["focus_ray"]=focus_ray
   is_camera["eye_axes"]=eye_axes

and commit the undo operation.

   m.commit_operation
end

UI.menu("Plugins").add_item("reveal view"){reveal_view}

Finally, we add a context menu option to call a method only on objects which contain the AttributeDictionary "is_a_camera". If the AttributeDictionary exists, then the option "go to view" is added to the context menu.

UI.add_context_menu_handler do |menu|
   select_one=Sketchup.active_model.selection[0]
   if select_one.class==Sketchup::Group
      if select_one.attribute_dictionary("is_a_camera",false)!=nil
         menu.add_item("go to view"){go_to_view(select_one)}
      end
   end
end

When this is clicked, it calls the go_to_view() method. Our second method, go_to_view(), will take a selected Entity and recall the values stored in the AttributeDictionary "is_a_camera". It then uses these values to return to the stored camera position and settings.

def go_to_view(sel)
   info=sel.attribute_dictionary("is_a_camera")
   m=Sketchup.active_model
   view=m.active_view
   view.camera=Sketchup::Camera.new(info["eye"],info["target"],
      info["up"],info["persp"],info["fov"])
end

wxSU and You

2008-10-23T14:48:00.000-07:00

Posted by Sang Ahn, SketchUp Software Engineer

A lot of you are already using the WebDialog of the SketchUp Ruby API to extend the user interface of SketchUp. Let's say you want something with a more native-application feel to it. Thanks to Peter Ellis of NREL, there's a neat plugin out there that allows you to do this. It comes with useful GUI elements that you can use in your own plugins such as a file-open dialog box, progress bar, etc.

It's built on top of wxRuby, so your UI implementation is cross-platform and you won't have to do any extra work. Best of all, it's FREE! Hats off to Peter.

Animate Yo' Cheese

2008-10-21T09:42:00.000-07:00

Posted by Scott Lininger, SketchUp Engineer

Drawing foodstuffs in SketchUp is fantastically cool, but at the end of the day you wind up with a meal that is, sigh, static. You can push your food about manually, of course, or you can hide or change its appearance by using scenes, but wouldn't it be fun if there were a way to make it animate on its own?

There are many plugins out there to help you create certain kinds of animations (Sketchy Physics and Podium are a couple that come to mind), but what if you're a gastric megalomaniac? What if you want to animate food using Ruby and thus have TOTAL CONTROL?

Glad you asked. Let's sling some code (and some gouda).

Our Example: Black hole ate my cheese

We're going to write a ruby script that allows you to right-click on any component and suck it magically to the model origin. (The origin is where the red, green, and blue axes of your model intersect.) It will work on any component, but especially well on cheese, 'cause it's delicious.

Step 1: Create our "move" method

The first thing we need to realize our dream of ballistic curds is code that moves a component one step at a time toward a target. There are lots of ways to create these kinds of tweening animations. We're going to use a simple averaging method, where the object moves halfway toward the destination with each call...

blackhole.rb

# Define our method that does the transform.
def move_halfway_toward(entity, target_pt)
  current_pt = entity.transformation.origin
  halfway = Geom::Point3d.linear_combination(0.5, current_pt, 0.5,
    target_pt)

  # Undo our current transform with inverse,
  # then move to the halfway point.
  entity.transform! entity.transformation.inverse
  entity.transform! Geom::Transformation.new halfway

  # Invalidate our view to force SU to refresh the screen.
  Sketchup.active_model.active_view.invalidate

end

# Create a rightclick handler that'll activate it.
UI.add_context_menu_handler do |context_menu|
  context_menu.add_item('Move halfway to origin') {
    entity = Sketchup.active_model.selection[0]
    origin_pt = Geom::Point3d.new 0, 0, 0
    move_halfway_toward(entity, origin_pt)
  }
end

Create this new file called blackhole.rb, and save it in your SketchUp/Plugins directory. When you restart SketchUp, you can now right click on Bryce (or any other component), and activate our new command. Do it over and over again and you can start to visualize a wheel of cheddar blazing through space. (Insert evil laugh here)

Step 2: use UI.start_timer to provide a timeline

Now we add a bit more to make the method fire again and again and again, auto-magically. The secret is SketchUp's UI.start_timer method, which instructs the API to call a snippet of code on a regular basis.

blackhole.rb (add these to the bottom of the existing file)

# Define our method that starts an animation.
def start_animation(entity, target_pt)

  # This calls our code snippet once every 10th of a second...
  frames_per_second = 10.0
  pause_length = 1.0 / frames_per_second

  timer_id = UI.start_timer(pause_length, true) {
  move_halfway_toward(entity, target_pt)
  # If we're within an inch of the origin, turn off the timer.
  new_location = entity.transformation.origin
  distance_from_target = new_location.distance target_pt
  if distance_from_target < 1.0
    UI.stop_timer timer_id
  end
  }
end

# Create a rightclick handler that'll activate it.
UI.add_context_menu_handler do |context_menu|
  context_menu.add_item('Animate to origin') {
  entity = Sketchup.active_model.selection[0]
  origin_pt = Geom::Point3d.new 0, 0, 0
  start_animation(entity, origin_pt)
  }
end

Restart SU, download some cheese, and get to animating! If you're motivated, you could try these fun, extra credit assignments:

Experiment with the frames_per_second to change the speed. (easy)

Use UI.inputbox to ask for an X, Y, Z location to animate to. (medium)

Send a raytest from the base of your cheese downward, to determine the nearest "ground" geometry, and have the cheese animate to land right on it! (tough)

Use a custom tool to activate animations with a single click! (semi-soft, with a salty rind)

Reading Textures from a SketchUp Model Using the Reader SDK

2008-09-29T16:16:00.000-07:00

Posted by Sang Ahn, SketchUp Software Engineer

In case you haven't looked yet, we have an SDK that allows you to read SketchUp files using a C++ interface. This allows you to write your own exporter for Google SketchUp or an importer for another application to read SketchUp files. Oftentimes you want all the polygons on your exported model to be triangles. Since most faces in a SketchUp model are quadrilateral polygons, you will need to triangulate the faces. Also, if a face has a texture you will want the uvq coordinates of the triangulated faces as well. Besides the face and the mesh that represents the face after it is triangulated, there are several other objects in the SketchUp Reader SDK that are used to read the uvq texture coordinates of a face. For example, there is the texture writer object. This is the object used to write out the face textures to disk. In order to retrieve the uvq texture coordinates of the mesh you also need a UV helper object and also a perspective object.
First, using the SkechUp document object, create the texture writer object:


ISkpApplication* sketchup_application = NULL;
sketchup_document->get_Application(&sketchup_application);
ISkpTextureWriter* texture_writer = NULL;
sketchup_application->CreateTextureWriter(&texture_writer);

Next, retrieve the ISkpCorrectPerspective interface of the texture writer:


ISkpCorrectPerspective* perspective = NULL;
texture_writer->QueryInterface(IID_ISkpCorrectivePerspective,
                               &perspective);

For each face retrieve its UV helper object using the perspective object:


ISkpUVHelper* uv_helper = NULL;
face->GetUVHelper(face,
                  true,  // front face
                  perspective,
                  &uv_helper);

Finally, create the triangulated mesh:


ISkpPolygonMesh* mesh = NULL;
face->CreateMesh(
     PolygonMeshPoints |
     PolygonMeshUVQFront |
     PolygonMeshUVQBack,
     perspective, &mesh);

Index through the vertices of the mesh and retrieve the position value of each vertex. If the face object belongs to a group or a component instance, the position needs to be transformed. The homogeneous transformation used to transform the position is the aggregate of the transformation of the parent group or component instance. If the parent is nested in other group(s) or component instance(s) then you the need to aggregate all the transformations.


double position[] = {0, 0, 0};
mesh->_GetPoint(index, position);

Finally, retrieve the uvq value that corresponds to the vertex position. The uvq value does not need to be transformed like the position value:


double uvq[] = {0, 0, 0};
uv_helper->GetFrontUVQ(
     position[0],
     position[1],
     position[2],
     &uvq[0],
     &uvq[1],
     &uvq[1]);

Stay tuned for further tips and tricks.

Inserting an External SketchUp Component (of some Pants)

2008-03-21T15:47:00.000-07:00

Posted by Scott Lininger, SketchUp Software Engineer

You've just SketchUped an amazing Robot Monkey, and you're ready to include him in your company brochure. Excitedly, you email the 3D PDF over to the legal department for approval, and you're faced with the biggest letdown of the whole project. They love it, they say, but due to new sensitivity around artificial animal companion rights, all Robot Monkeys must be modestly clothed before being released to the public.

Fortunately, you anticipated this problem and have a very nice model of some respectable trousers. Now you just need to insert them into your model, preferably by using the Ruby API.

If you know the exact file path to the SKP file that you'd like to insert, your job is simple. Just type these lines into the Ruby console (replace the "C:\pants.skp" with the absolute path to your component.)

pants_def = Sketchup.active_model.definitions.load("C:\pants.skp")
Sketchup.active_model.place_component(pants_def)

If everything typed out okay, then you should be inserting some snazzy pants using the standard "place component" tool. Hooray!

"But that's not very useful," you say, "It's easier to use the Component Browser to do that! What if I don't know the path to my pants? What if you want to place my pants in a particular spot?"

Okay, okay. Here's a more complete snippet that keeps the power in the control of the Ruby.

# First, load our pants (heh). This time we'll search for
# the file inside our Components directory.
pants_path = Sketchup.find_support_file "pants.skp" ,"Components"
pants_def = model.definitions.load pants_path

# Then define a location, and place our pants there.
pants_location = Geom::Point3d.new 100,200,0
transform = Geom::Transformation.new pants_location
entities = Sketchup.active_model.active_entities
instance = entities.add_instance pants_def, transform

And at long last, your Monkey has Pants, and you're the new company hero!

Sharing data between SketchUp Ruby and Javascript

2008-02-19T08:11:00.000-08:00

Posted by Scott Lininger, SketchUp Software Engineer

If you are building rich WebDialogs in your SketchUp Plugin, then you are probably using Javascript + DHTML (Dynamic HTML) to show the UI and handle user input. In practical terms, this means that you could easily have as much Javascript code in your plugin as Ruby code! But the SketchUp API documentation doesn't give much guidance on using Javascript to talk to SketchUp. What's a coder to do?

Sharing data between Javascript and Ruby can be a bit of a black art. The Ruby API provides two mechanisms that we can leverage:

1. WebDialog.add_action_callback() allows us to define a Ruby method that a WebDialog can call. This allows us to send data DOWN from Javascript to Ruby.

2. WebDialog.execute_script() allows us to run a bit of Javascript code from inside Ruby. This allows us to send data UP from Ruby to Javascript.

By using these two mechanisms together, we can create a nice, generic way for Javascript to get whatever it needs from Ruby.

Step 1: Using add_action_callback to request some data
For our example, let's imagine we have two files inside our Plugins directory: selectionInfo.rb and selectionInfo.html. Together, these files provide a new feature to SketchUp: a floating window that shows us how many objects are selected inside SketchUp.

Our first step is to show a WebDialog and establish our action callback. Here's the minimal code required to make this work:

selectionInfo.rb
# Create the WebDialog instance
my_dialog = UI::WebDialog.new("Selection Info", false, "Selection Info", 200, 200, 200, 200, true)

# Attach an action callback
my_dialog.add_action_callback("get_data") do |web_dialog,action_name|
UI.messagebox("Ruby says: Your javascript has asked for " + action_name.to_s)
end

# Find and show our html file
html_path = Sketchup.find_support_file "selectionInfo.html" ,"Plugins"
my_dialog.set_file(html_path)
my_dialog.show()

selectionInfo.html
<html>
<script>
function callRuby(actionName) {
query = 'skp:get_data@' + actionName;
window.location.href = query;
}
</script>
<body>
<h3 id="output">You have 0 things selected.</h3>
<input type="button" onclick="callRuby('pull_selection_count')" value="Refresh">
</body>
</html>

If you create these two files and save them into your Plugins directory, you'll see a very simple WebDialog the next time you restart SketchUp. Click on the "Refresh" button and you'll see a messagebox that was generated by our Ruby (but controlled based on data from the Javascript.)

Make sense? We now have a mechanism for sending data down to Ruby, which is a way for Javascript to ask Ruby a question. Now we just need Ruby to provide an answer...

Step 2: Using execute_script to send some data
The next step in our data sharing scheme requires us to respond. Let's add a few lines of code to our files... (Changed code is highlighted in yellow.)

selectionInfo.rb
# Create the WebDialog instance
my_dialog = UI::WebDialog.new("Selection Info", false, "Selection Info", 200, 200, 200, 200, true)

# Attach an action callback
my_dialog.add_action_callback("get_data") do |web_dialog,action_name|
if action_name=="pull_selection_count"
total_selected = Sketchup.active_model.selection.length
js_command = "passFromRubyToJavascript("+ total_selected.to_s + ")"
web_dialog.execute_script(js_command)
end
end

# Find and show our html file
html_path = Sketchup.find_support_file "selectionInfo.html" ,"Plugins"
my_dialog.set_file(html_path)
my_dialog.show()

selectionInfo.html
<html>
<script>
function callRuby(actionName) {
query = 'skp:get_data@' + actionName;
window.location.href = query;
}

function passFromRubyToJavascript(value) {
var message = "You have " + value + " items selected.";
document.getElementById('output').innerHTML = message;
}
</script>
<body>
<h3 id="output">You have 0 things selected.</h3>
<input type="button" onclick="callRuby('pull_selection_count')" value="Refresh">
</body>
</html>

Save these changes, and then restart SketchUp. Now when you click on the "Refresh" button, you get an updated web page showing the number of objects selected.

Looking ahead: Using JSON for more complex data
We've been working with an extremely simple example where we're passing a single number. In a real world application you would probably be sending more complex data. In this case, JSON (Javascript Object Notation) is the perfect mechanism. It's a way where you can pass nested objects and arrays in a single command.

We'll explore more about JSON in a future blog post. But for now, consider the following example.

# Passing lots of data about a component
js_command = "passFromRubyToJavascript({typename:'ComponentInstance',name:'Bryce',x:10.5,y:13.5,z:0.0})"
web_dialog.execute_script(js_command)

This kind of approach is a great way to allow Javascript to get large, structured data sets out of SketchUp whenever your application needs them. Stay tuned for a deeper exploration of this idea.

WebDialog

2007-12-19T10:37:00.000-08:00

Posted by Sang Ahn, SketchUp Software Engineer

One of the interesting features of SketchUp's Ruby API is the UI::WebDialog class. Since WebDialog supports DHTML and JavaScripts, you can provide a rich, custom user experience for your SketchUp plugin users. You may be thinking, just another dialog box pretending to be a browser-lite, right? But there's more: with WebDialog you can call Ruby code from within the DHTML content of the dialog's document. No, this isn't some kind of listen-to-port-80-and-redirect trick. You define a block of execution in your Ruby code, assign it to the WebDialog object by name, and when the user selects the input element with that name the block is executed. Let's say you have an input element such as this:

<a href="skp:myAction@Hello">say hi!</a>

Now, all you have to do is define a block of execution and assign it with the name "myAction."

dialog.add_action_callback("myAction") { |d, p| puts p }

When the user clicks on the input element, it's the equivalent to

proc = Proc.new { |d, p| puts d}
proc.call(dialog, "Hello")

Simple and useful.

Hello World

2007-12-14T10:15:00.000-08:00

Posted by the SketchUp API team

Welcome to the Google SketchUp API Blog. We are very excited to have this venue to post information and updates for developers who are creating tools and exporters for SketchUp. This blog will cover both the SketchUp Ruby API and the SketchUp SDK (beta). We hope to be posting regularly about new API features and fixes, and from time to time we'll also be sharing examples of what you can do with our API's. We encourage you to post any comments and concerns you have, and look forward to hearing from you!