Model

class Model

Parent: Object | Class Index
Methods: abort_operation, active_entities, active_layer, active_layer=, active_view, add_note, attribute_dictionaries, attribute_dictionary, bounds, commit_operation, definitions, description, description=, entities, get_attribute, get_datum, guid, latlong_to_point, layers, list_datums, materials, modified?, options, pages, path, place_component, point_to_latlong, point_to_utm, raytest, rendering_options, save, save_thumbnail, select_tool, selection, set_attribute, set_datum, shadow_info, start_operation, title, utm_to_point, valid? |
Sample Code: modeltests.rb |

This is the interface to a SketchUp model.

Instance Methods

abort_operation
The abort_operation method aborts the current operation started with the start_operation method.
Syntax:
status = model.abort_operation
Arguments:
Return Value:
status – true if successful, false if unsuccessful
Comments:
The abort_operation method is normally called from inside of a rescue clause to cancel an operation if something goes wrong.
Example:
status = model.abort_operation

active_entities
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)
Syntax:
entities = model.active_entities
Arguments:
Return Value:
entities – an entities object
Comments:
Example:
model=Sketchup.active_model entities=model.active_entities

active_layer
The active_layer method retrieves the active Layer.
Syntax:
layer = model.active_layer
Arguments:
Return Value:
layer – a layer object containing the currently active layer
Comments:
The default layer in SketchUp is layer 0.
Example:

active_layer =
The active_layer= method sets the active Layer object.
Syntax:
activelayer = model.active_layer=layer
Arguments:
layer – the layer object to be set as the active layer
Return Value:
activelayer – the newly set active layer object
Comments:
Example:

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

active_view
The active_view method returns the active View object for this model.
Syntax:
view = model.active_view
Arguments:
Return Value:
view – a view object
Comments:
Example:
model = Sketchup.active_model view = model.active_view

add_note
The add_note method is used to add a text note to the model.
Syntax:
note = Sketchup.active_model.add_note “note” x, y
Arguments:
“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
Return Value:
note – a note object or an exception if it is unsuccessful.
Comments:
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.
Example:

model = Sketchup.active_model

begin
note = mode.add_note “Test Note”, 0.1, 0.1
rescue
UI.messagebox $!.message
end

attribute_dictionaries
The attribute_dictionaries method retrieves the AttributeDictionaries object that is associated with the Model.
Syntax:
attributedictionaries = model.attribute_dictionaries
Arguments:
Return Value:
attributedictionaries – an array of attribute dictionary if successful, nil if there are no attribute dictionaries
Comments:
Example:

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

attribute_dictionary
The attribute_dictionary method retrieves an attribute dictionary with a given name that is associated with the model.
Syntax:
attributedictionary = model.attribute_dictionary “name” create
Arguments:
“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
Return Value:
attributedictionary – an attribute dictionary object if successful, nil if unsuccessful
Comments:
The model and entities do not have attribute dictionaries by default. You must create model-related attribute dictionaries using the create flag.
Example:

bounds
The bounds method retrieves the bounding box of the model.
Syntax:
boundingbox = model.bounds
Arguments:
Return Value:
boundingbox = a bounding box for the model if successful
Comments:
Example:

model = Sketchup.bounds
bounds = model.bounds

if (bounds)
length = bounds.length
UI.messagebox length
else
UI.messagebox “Failure: No bounding box found”
end

commit_operation
The commit_operation method commits an operation for undo.
Syntax:
status = model.commit_operation
Arguments:
Return Value:
status – true if successful, false if unsuccessful
Comments:
The commit_operation method is normally called at the end of a method to commit the operation that the method performs.
Example:
status = model.commit_operation

definitions
The definitions method retrieves a definition list containing all of the component definitions in the model.
Syntax:
definitionslist = model.definitions
Arguments:
Return Value:
definitions – a definitions list if successful.
Comments:
The returned definitions can be empty.
Example:
model = Sketchup.model deflist = model.definitions # parse array of definitions and act upon the definitions found

description
The description method retrieves a description of the model as found in the Model Info > Files panel.
Syntax:
description = model.description
Arguments:
Return Value:
description – a description if successful.
Comments:
The returned description can be empty. The default description for all models is empty.
Example:
model = Sketchup.model desc = model.description

description=
The description= method sets the description of the model.
Syntax:
description = model.description “description”
Arguments:
“description” – (optional) the description string to be set.
Return Value:
description – the currently set description string.
Comments:
If you do not include a description string, the description is cleared and an empty description is returned.
Example:
model = Sketchup.model description = model.description=”This is a model of a house on the North West Corner of 10th and Dolores Street in Carmel, California”

entities
The entities method returns an Entities object containing an array of entities in the model.
Syntax:
entities = model.entities
Arguments:
Return Value:
entities – an Entities object if successful
Comments:
If no entities are in your model, this method returns an empty Entities object (an empty array)
Example:
model = Sketchup.model entities = model.entities # Add a group to the entities in the model entities = entities.addgroup

get_attribute
The get_attribute method gets the value of an attribute that in the AttributeDictionary with the given name.
Syntax:
value = model.get_attribute “dictionaryname”, key, defaultvalue
Arguments:
“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
Return Value:
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.
Comments:
Example:

get_datum
the get_datum method retrieves the datum, in the form of a string, used in UTM conversions.
Syntax:
datum = model.get_datum
Arguments:
Return Value:
datum – a datum represented as a string if successful.
Comments:
Example:
model = Sketchup.active_model datum = model.get_datum

guid
The guid method retrieves the globally unique identifier, in the form of a string, for the Model.
Syntax:
guid = model.guid
Arguments:
Return Value:
guid – a globally unique identifier, in the form of a string, for the model
Comments:
Example:
model = Sketchup.active_model guid = model.guid

latlong_to_point
The latlong_to_point method convert a latitude and longitude to a Point3d object in the model.
Syntax:
point = model.latlong_to_point latlong
Arguments:
latlong – a latlong object
Return Value:
point – a point3d object if successful, false if unsuccessful.
Comments:
Example:

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

layers
The layers method retrieves a collection of all Layers objects in the model.
Syntax:
layers = model.layers
Arguments:
Return Value:
layers – a Layers object containing a collection of Layers in the model
Comments:
Example:
model = Sketchup.active_model layers = model.layers

list_datums
This method retrieves an Array of all of the datums recognized by SketchUp.
Syntax:
datums = model.list_datums
Arguments:
Return Value:
datums – An Array object containing the datums supported by SketchUp
Comments:
Example:

model = Sketchup.active_model
datums = model.list_datums

if (datums)
# display a paragraph with all of the datums
UI.messagebox datums
end

materials
The materials method returns a collection of all of the Materials in the model.
Syntax:
materials = model.materials
Arguments:
Return Value:
Comments:
Example:

model = Sketchup.active_model
materials = model.materials

if (materials)
# List number of materials
count = materials.count
UI.messagebox count
end

modified?
The modified? method determines if the Model has been modified since the last save.
Syntax:
status = model.modified?
Arguments:
Return Value:
status = true if the model has been modified since last save (and requires a save), false if the model has not been modified.
Comments:
Example:

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

options
The options method retrieves the options manager that defines the options settings for the model.
Syntax:
optionsmanager = model.options
Arguments:
Return Value:
optionsmanager – an OptionsManager object containing one or more options providers if successful.
Comments:
There are 5 default options managers. These are: PageOptions, AxisOptions, SlideshowOptions, UnitsOptions, and NamedOptions.
Example:

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

pages
The pages method retrieves a Pages object containing all of the pages in the Model.
Syntax:
pages = model.pages
Arguments:
Return Value:
pages – returns a Pages object with 0 or more pages.
Comments:
Example:

model = Sketchup.model
pages = model.pages
# Add a page to the Pages object
page = pages.add
size = pages.size
# Size should be 1
UI.messagebox size

path
The path method retrieves the path of the file from which the model was opened.
Syntax:
path = model.path
Arguments:
Return Value:
path – an string containing the path for the currently opened model.
Comments:
An empty string is returned for a new model (one which has not been saved and opened)
Example:
model = Sketchup.model # Return the current path (empty) path = model.path UI.messagebox path

place_component
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.
Syntax:
status = model.placecomponent componentdefinition, repeat
Arguments:
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
Return Value:
Comments:
Example:

point_to_latlong
The point_to_latlong method converts a point in the model to a LatLong so that you can get its latitude and longitude.
Syntax:
latlong = model.point_to_latlong point
Arguments:
point – a Point3d object
Return Value:
latlong – a LatLong object
Comments:
This method uses the location information set in ShadowInfo.
Example:

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

point_to_utm
This method converts a Point3d object in the Model to UTM coordinates.
Syntax:
utm = model.point_to_utm(point)
Arguments:
point – A Point3d object
Return Value:
utm – a UTM object
Comments:
This method uses the location information set in ShadowInfo. See also UTM.
Example:

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

raytest
Cast a ray through the model and return the first thing that it hits.
Syntax:
Arguments:
Return Value:
Comments:
Example:

rendering_options
The rendering_options method retrieves the RenderingOptions object for this Model.
Syntax:
renderingoptions = model.rendering_options
Arguments:
Return Value:
renderingoptions – a RenderingOptions object
Comments:
Example:

save
This method is used to save the model to a file.
Syntax:
status = model.save “filename”
Arguments:
“filename” – the name of the file to save
Return Value:
status – true if successful, false if unsuccessful
Comments:
Example:
model = SketchUp.active_model status = model.save “mysketchup.skp”

save_thumbnail
The save_thumbnail method is used to save a thumbnail image to a file.
Syntax:
status = model.save_thumbnail "filename"
Arguments:
"filename" - the name of the file, with extension, to save the thumbnail as
Return Value:
status - true if successful, false if unsuccessful
Comments:
Returns nil if it is an internal component.
Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
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 model
face = entities.add_face pts
status = model.save_thumbnail "testthumbnail2.jpg"
UI.messagebox status

select_tool
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.
Syntax:
tool = model.select_tool tool
Arguments:
tool – the Tool object you want to select.
Return Value:
tool – A Tool object.
Comments:
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.
Example:
model = Sketchup.active_model tool = model.select_tool nil

selection
This method retrieves a Selection object for the model, containing the currently selected entities.
Syntax:
selection = model.selection
Arguments:
Return Value:
selection – A Selection object with 0 or more entities that are currently selected.
Comments:
Example:
model = Sketchup.active_model selection = model.selection

set_attribute
This method is used to set the value of an attribute in an attribute dictionary with the given name.
Syntax:
value = model.set_attribute “attributedictionaryname”, “key”, “value”
Arguments:
“attributedictionaryname” – the name of the attribute dictionary whose attribute you wish to set “key” – the attribute name “value” – the value to set
Return Value:
value – the value that was set
Comments:
This method can be used create a new AttributeDictionary object, if needed.
Example:
model = Sketchup.active_model value = model.set_attribute “testdictionary” “test” “115”

set_datum
This method sets the datum used in conversions between the internal coordinate system and UTM.
Syntax:
value = model.setdatum "datum"
Arguments:
Return Value:
Comments:
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.
Example:
model = Sketchup.active_model value = model.set_datum “Adindan”

shadow_info
This method is used to retrieve the shadow information for the Model.
Syntax:
shadowinfo = model.shadow_info
Arguments:
Return Value:
shadowinfo – a ShadowInfo object.
Comments:
Example:
model = Sketchup.active_model shadowinfo = model.shadow_info

start_operation
The start_operation method is used to notify Edit > Undo that a new operation (which can be undone) is starting.
Syntax:
status = model.start_operation
Arguments:
Return Value:
status – true if successful, false if unsuccessful
Comments:
The String is a description for the operation that is displayed adjacent to the Edit > Undo menu item.
Example:
status = model.start_operation

title
The tile method retrieves the name of the model.
Syntax:
title = model.title
Arguments:
Return Value:
title – the title of the model or an empty string (if the title is not set)
Comments:
Example:
model = Sketchup.active_model title = model.title

utm_to_point
The utm_to_point method converts a position given in UTM coordinates to a Point3d in the Model.
Syntax:
point = model.utm_to_point utm
Arguments:
utm – a UTM object.
Return Value:
point - A Point3d object.
Comments:
Example:

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

valid?
The valid method determines if the model is valid.
Syntax:
status = model.valid?
Arguments:
Return Value:
status – true if the model is valid, false if it is invalid.
Comments:
Example:
model = Sketchup.active_model valid = model.valid?