|
SketchUp Ruby API Reference |
This is the interface to a SketchUp model.
Parent: Object
Methods: abort_operation, active_entities, active_layer, active_layer=, active_view, add_note, add_observer, attribute_dictionaries, attribute_dictionary, behavior, bounds, close_active, commit_operation, definitions, description, description=, entities, export, get_attribute, get_datum, guid, import, latlong_to_point, layers, list_datums, materials, modified?, options, pages, path, place_component, point_to_latlong, point_to_utm, raytest, remove_observer, rendering_options, save, save_thumbnail, select_tool, selection, set_attribute, set_datum, shadow_info, start_operation, styles, title, tools, utm_to_point, valid?
Example Code: modeltests.rb
The abort_operation method aborts the current operation started with the start_operation method.
status = model.abort_operation
status – true if successful, false if unsuccessful
The abort_operation method is normally called from inside of a rescue clause to cancel an operation if something goes wrong.
status = model.abort_operation
The active_entities method is used to retrieve an Entities object containing all of the entities in the active model or component (if you are within a component)
entities = model.active_entities
entities – an entities object
model=Sketchup.active_model entities=model.active_entities
The active_layer method retrieves the active Layer.
layer = model.active_layer
layer – a layer object containing the currently active layer
The default layer in SketchUp is layer 0.
model = Sketchup.active_model
layers = model.layers
layers.add “My Layer”
activelayer = model.active_layer=layers[1]
layer=model.active_layer
The active_layer= method sets the active Layer object.
activelayer = model.active_layer=layer
layer – the layer object to be set as the active layer
activelayer – the newly set active layer object
model = Sketchup.active_model
layers = model.layers
layers.add “My Layer”
activelayer = model.active_layer=layers[1]
layer=model.active_layer
name = layer.name
if (name != “My Layer”)
UI.messagebox “Failure: wrong Layer”
else
UI.messagebox name
end
The active_view method returns the active View object for this model.
view = model.active_view
view – a view object
model = Sketchup.active_model
view = model.active_view
The add_observer method is used to add an observer to the current object.
status = object.add_observer observer
observer - an observer
true if successful, false if unsuccessful.
The add_note method is used to add a text note to the model.
note = Sketchup.active_model.add_note “note” x, y
“note” – a string note
x – a distance along the x axis between 0 and 1
y – a distance along the y axis between 0 and 1
note – a note object or an exception if it is unsuccessful.
The position of the note is given as relative window positions between 0 and 1. For example, the following command would create a note that start one-tenth of the way down the screen from the upper left corner of the window.
model = Sketchup.active_model
begin
note = mode.add_note “Test Note”, 0.1, 0.1
rescue
UI.messagebox $!.message
end
The attribute_dictionaries method retrieves the AttributeDictionaries object that is associated with the Model.
attributedictionaries = model.attribute_dictionaries
attributedictionaries – an array of attribute dictionary if successful, nil if there are no attribute dictionaries
model = Sketchup.active_model
attdicts = model.attribute_dictionaries
if (attdicts)
# code to do something if attribute dictionaries exist (usually you parse the array of
# dictionaries
else
# code to do something if attribute dictionaries do not exist
end
The attribute_dictionary method retrieves an attribute dictionary with a given name that is associated with the model.
attributedictionary = model.attribute_dictionary “name” create
“name” – the name of the dictionary you are attempting to retrieve
create – (optional) if set to true an attribute dictionary of the given “name” will be created if not found
attributedictionary – an attribute dictionary object if successful, nil if unsuccessful
The model and entities do not have attribute dictionaries by default. You must create model-related attribute dictionaries using the create flag.
The behavior method retrieves the behavior of the model.
behavior = model.behavior
behavior = a behavior object for the model if successful
model = Sketchup.active_model
behavior = model.behaviorif (behavior)UI.messagebox behaviorelseUI.messagebox "Failure"end
The bounds method retrieves the bounding box of the model.
boundingbox = model.bounds
boundingbox = a bounding box for the model if successful
model = Sketchup.bounds
bounds = model.bounds if (bounds)
length = bounds.length
UI.messagebox length
else
UI.messagebox “Failure: No bounding box found”
end
The close_active method is used to close the currently active (open) group or component.
status = close_active
status - true if successful, false if unsuccessful.
The commit_operation method commits an operation for undo.
status = model.commit_operation
status – true if successful, false if unsuccessful
The commit_operation method is normally called at the end of a method to commit the operation that the method performs.
status = model.commit_operation
The definitions method retrieves a definition list containing all of the component definitions in the model.
definitionslist = model.definitions
definitions – a definitions list if successful.
The returned definitions can be empty.
model = Sketchup.active_model
deflist = model.definitions
# parse array of definitions and act upon the definitions found
The description method retrieves a description of the model as found in the Model Info > Files panel.
description = model.description
description – a description if successful.
The returned description can be empty. The default description for all models is empty.
model = Sketchup.active_model desc = model.description
The description= method sets the description of the model.
description = model.description “description”
“description” – (optional) the description string to be set.
description – the currently set description string.
If you do not include a description string, the description is cleared and an empty description is returned.
model = Sketchup.active_model description = model.description=”This is a model of a house on the North West Corner of 10th and Dolores Street in Carmel, California”
The entities method returns an Entities object containing an array of entities in the model.
entities = model.entities
entities – an Entities object if successful
If no entities are in your model, this method returns an empty Entities object (an empty array)
model = Sketchup.active_model
entities = model.entities # Add a group to the entities in the model
entities = entities.addgroup
The export method is used to export to the specified file format by recognizing the given file extension and calling the appropriate exporter.
status = model.import "filename", show_summary
“filename” – the name of the file to import.
show_summary - true if you want to show a summary window, false if you do not want to show a summary window.
status – true if successful, false if unsuccessful
The get_attribute method gets the value of an attribute that in the AttributeDictionary with the given name.
value = model.get_attribute “dictionaryname”, key, defaultvalue
“dictionaryname” – the name of the dictionary containing the value
“key” – the key containing the value
defaultvalue – (optional) default value that will be returned if a value does not exist
value – the value for a given key in the given dictionary if a value exists; the default value if a defaultvalue is provided and the value does not exist; nil if the value does not exist and no defaultvalue is provided.
the get_datum method retrieves the datum, in the form of a string, used in UTM conversions.
datum = model.get_datum
datum – a datum represented as a string if successful.
model = Sketchup.active_model datum = model.get_datum
The guid method retrieves the globally unique identifier, in the form of a string, for the Model.
guid = model.guid
guid – a globally unique identifier, in the form of a string, for the model
model = Sketchup.active_model guid = model.guid
The import method is used to load a file by recognizing the file extension and calling appropriate importer.
status = model.import "filename", show_summary
“filename” – the name of the file to import.
show_summary - true if you want to show a summary window, false if you do not want to show a summary window.
status – true if successful, false if unsuccessful
The latlong_to_point method convert a latitude and longitude to a Point3d object in the model.
point = model.latlong_to_point latlong
latlong – a latlong object
point – a point3d object if successful, false if unsuccessful.
latitude = [40.01700, 105.28300]
model = Sketchup.active_model
begin
latlong = Geom::LatLong.new(latitude)
rescue
UI.messagebox $!.message
end
point = model.latlong_to_point latlong
The layers method retrieves a collection of all Layers objects in the model.
layers = model.layers
layers – a Layers object containing a collection of Layers in the model
model = Sketchup.active_model layers = model.layers
This method retrieves an Array of all of the datums recognized by SketchUp.
datums = model.list_datums
datums – An Array object containing the datums supported by SketchUp
model = Sketchup.active_model
datums = model.list_datums
if (datums)
# display a paragraph with all of the datums
UI.messagebox datums
end
The materials method returns a collection of all of the Materials in the model.
materials = model.materials
model = Sketchup.active_model
materials = model.materials
if (materials)
# List number of materials
count = materials.count
UI.messagebox count
end
The modified? method determines if the Model has been modified since the last save.
status = model.modified?
status = true if the model has been modified since last save (and requires a save), false if the model has not been modified.
model = Sketchup.active_model
entities = model.active_entities
# Add a group to force the status return value to be true
entities.add_group
status = model.modified? if (status)
# If status is true, the following message is displayed
UI.messagebox “You better save soon.”
end
The options method retrieves the options manager that defines the options settings for the model.
optionsmanager = model.options
optionsmanager – an OptionsManager object containing one or more options providers if successful.
There are 5 default options managers. These are: PageOptions, AxisOptions, SlideshowOptions, UnitsOptions, and NamedOptions.
model = Sketchup.active_model
optionsmanager = model.options
if (optionsmanager)
# If an options manager is returned, iterate through each option provider within the
# options
# options manager and display its name.
size = optionsmanager.size
UI.messagebox size
for option in optionsmanager
option = optionsmanager[x]
name = optionsmanager.name
UI.messagebox name
x = x + 1
end
else
UI.messagebox “Failure”
end
The pages method retrieves a Pages object containing all of the pages in the Model.
pages = model.pages
pages – returns a Pages object with 0 or more pages.
model = Sketchup.active_model
pages = model.pages
# Add a page to the Pages object
page = pages.add
size = pages.size
# Size should be 1
UI.messagebox size
The path method retrieves the path of the file from which the model was opened.
path = model.path
path – an string containing the path for the currently opened model.
An empty string is returned for a new model (one which has not been saved and opened)
model = Sketchup.active_model
# Return the current path (empty)
path = model.path
UI.messagebox path
The place_component method places a new component in the Model using the component placement tool.
The first argument is a ComponentDefinition. There is a second optional argument. If it is true, it says to stay in the tool and place multiple instances of the component.
status = model.placecomponent componentdefinition, repeat
componentdefinition – A component definition object containing the definition (blueprint) for the component
repeat – if set to true, stay in the component placement tool and place multiple components
The point_to_latlong method converts a point in the model to a LatLong so that you can get its latitude and longitude.
latlong = model.point_to_latlong point
point – a Point3d object
latlong – a LatLong object
This method uses the location information set in ShadowInfo.
coordinates = [10,10,10]
model = Sketchup.active_model
begin
point = Geom::Point3d.new(coordinates)
rescue
UI.messagebox $!.message
end latlong = model.point_to_latlong(point) if (latlong)
# if a latlong object was returned, convert contents to a string
latlongvalue = latlong.to_s
UI.messagebox latlongvalue
else
UI.messagebox “Failure”
end
This method converts a Point3d object in the Model to UTM coordinates.
utm = model.point_to_utm(point)
point – A Point3d object
utm – a UTM object
This method uses the location information set in ShadowInfo. See also UTM.
coordinates = [10,10,10]
model = Sketchup.active_model begin
point = Geom::Point3d.new(coordinates)
rescue
UI.messagebox $!.message
end utm = model.point_to_utm(point)
if (utm)
# if a utm object was returned, convert contents to a string
utmvalue = utm.to_s
UI.messagebox utmvalue
else
UI.messagebox “Failure”
end
The raytest method is used to cast a ray (line) through the model and return the first thing that the ray hits.
item - model.raytest ray
ray - a two element array containing a point and a vector
item - an array of two values. The first value is a Point3d where the item that the ray passed through exists. The second element is the instance path array of the entity that the ray hit. For example, if the ray hits a face that contained by a component instance the instance path would be [Component1]. If the ray hit a face that is contained by a component instance, which is contained by another component instance and so on, the instance path would be [Component1, Component2, Componten3...].
A ray is a two element array containing a point and a vector [Geom::Point3d(), Geom::Vector3d()]. The point defines the start point of the ray and the vector defines the direction.
The remove_observer method is used to remove an observer from the current object.
status = object.remove_observer observer
observer - an observer
true if successful, false if unsuccessful.
'
The rendering_options method retrieves the RenderingOptions object for this Model.
renderingoptions = model.rendering_options
renderingoptions – a RenderingOptions object
model = Sketchup.active_model
begin
renderingoptions = model.rendering_options
rescue
UI.messagebox $!.message
end
if (renderingoptions)
option = renderingoptions[0]
UI.messagebox option
else
UI.messagebox "Failure"
end
This method is used to save the model to a file.
status = model.save “filename”
“filename” – the name of the file to save
status – true if successful, false if unsuccessful
model = SketchUp.active_model
status = model.save “mysketchup.skp”
The save_thumbnail method is used to save a thumbnail image to a file.
status = model.save_thumbnail "filename"
"filename" - the name of the file, with extension, to save the thumbnail as
status - true if successful, false if unsuccessful
Returns nil if it is an internal component.
depth = 100width = 100model = Sketchup.active_modelentities = model.active_entitiespts = []pts[0] = [0, 0, 0]pts[1] = [width, 0, 0]pts[2] = [width, depth, 0]pts[3] = [0, depth, 0]# Add the face to the entities in the modelface = entities.add_face ptsstatus = model.save_thumbnail "testthumbnail2.jpg"UI.messagebox status
This method is used to select a SketchUp Tool object as the active tool. You must implement the SketchUp Tool interface to create a tool prior to calling this method.
tool = model.select_tool tool
tool – the Tool object you want to select.
tool – A Tool object.
The select tool is returned if you pass nil to the select_tool method. You must implement the SketchUp Tool interface to create a tool, prior to calling this method, and then instance the tool implementation and pass the object to this method.
model = Sketchup.active_model
tool = model.select_tool nil
This method retrieves a Selection object for the model, containing the currently selected entities.
selection = model.selection
selection – A Selection object with 0 or more entities that are currently selected.
model = Sketchup.active_model
selection = model.selection
This method is used to set the value of an attribute in an attribute dictionary with the given name.
value = model.set_attribute “attributedictionaryname”, “key”, “value”
“attributedictionaryname” – the name of the attribute dictionary whose attribute you wish to set
“key” – the attribute name
“value” – the value to set
value – the value that was set
This method can be used create a new AttributeDictionary object, if needed.
model = Sketchup.active_model value = model.set_attribute “testdictionary” “test” “115”
This method sets the datum used in conversions between the internal coordinate system and UTM.
value = model.setdatum "datum"
The default datum is WGS84. You can use the method list_datums to get a list of all of the datums supported in SketchUp. If you pass an invalid datum to set_datum, set_datum returns the default datum.
model = Sketchup.active_model value = model.set_datum “Adindan”
This method is used to retrieve the shadow information for the Model.
shadowinfo = model.shadow_info
shadowinfo – a ShadowInfo object.
model = Sketchup.active_model shadowinfo = model.shadow_info
The start_operation method is used to notify Edit > Undo that a new operation (which can be undone) is starting.
status = model.start_operation
status – true if successful, false if unsuccessful
The String is a description for the operation that is displayed adjacent to the Edit > Undo menu item.
status = model.start_operation
The styles method retrieves the styles associated with the model.
styles = model.styles
styles – the Styles object if successful
The tile method retrieves the name of the model.
title = model.title
title – the title of the model or an empty string (if the title is not set)
model = Sketchup.active_model title = model.title
The tools method is used to retrieve the current Tools object.
tools = model.tools
tools - a Tools object.
The utm_to_point method converts a position given in UTM coordinates to a Point3d in the Model.
point = model.utm_to_point utm
utm – a UTM object.
point - A Point3d object.
point = [10,10,10]
model = Sketchup.active_model
begin
point = Geom::Point3d.new(point)
rescue
UI.mesagebox $!.message
end # Create a UTM object from the point
utm = model.point_to_utm point
# Pass that UTM object right back into utm_to_point to get the UTM back again
point = model.utm_to_point utm if (point)
pointvalue = point.to_s
UI.messagebox pointvalue
else
UI.messagebox “Failure”
end
The valid method determines if the model is valid.
status = model.valid?
status – true if the model is valid, false if it is invalid.
model = Sketchup.active_model valid = model.valid?