New User's Comments Feature on the Google SketchUp Ruby API documentation site
Google Code is running a pilot on user-contributed notes to the API documentation. This feature is currently enabled for the documentation of a handful of products, including the Google SketchUp Ruby API! The ultimate goal of this feature is to provide a richer documentation experience for our developers, similar to that offered in open source projects such as php.net.
We invite you to participate by adding notes, insights, or code examples to a particular doc. Your note may take up to 24 hours to appear after you submit it. All notes will be moderated to ensure they provide a useful contribution to the topic to which they are attached. Requests for help with the API should not be submitted as notes, but should continue to be posted to the Google SketchUp Developers Google Group.
Last month we released a 2nd update for SketchUp 7.1. This release includes a few bug fixes as well as fixes for two reported security issues. Were happy to announce that we have also updated the SDK package with the same security fixes. Please note that the file format for the 7.1 M2 has not changed but we do recommend that folks upgrade to the latest version. It can be downloaded from the SDK page on our code site. If you'd like more info on this update please see our original blog post for the release.
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.
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.
# 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
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.
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.
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.
