This is the interface to a SketchUp model. The model is the 3D drawing that the user is working with, and it serves as the "entry point" for most Ruby API interactions. The Sketchup.active_model method gives you a handle to the current model, and from there you can use the model-level methods to start getting information and making changes.
|
# Grab a handle to the currently active model (aka the one the user is
# looking at in SketchUp.)
model = Sketchup.active_model
# Grab other handles to commonly used collections inside the model.
entities = model.entities
layers = model.layers
materials = model.materials
component_definitions = model.definitions
selection = model.selection
# Now that we have our handles, we can start pulling objects and making
# method calls that are useful.
first_entity = entities[0]
UI.messagebox("First thing in your model is a " + first_entity.typename)
number_materials = materials.length
UI.messagebox("Your model has " + number_materials.to_s + " materials.")
new_edge = entities.add_line( [0,0,0], [500,500,0])
The abort_operation method aborts the current operation started with the
start_operation method.
The abort_operation method is normally called from inside of a rescue clause
to cancel an operation if something goes wrong.
Returns:
status = model.abort_operation
The active_entities method is used to retrieve an Entities object containing all of the entities in the active model, component, or group (if you are within a group or component edit session.)
Returns:
model = Sketchup.active_model entities = model.active_entities
The active_layer method retrieves the active Layer.
The default layer in SketchUp is layer 0.
Returns:
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.
Arguments:
Returns:
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
Returns an array containing the sequence of entities the user has
double-clicked on for editing. This allows one to determine whether they are
in component edit mode and where in the model they are.
For example, if a user has double-clicked into a component to
edit its geometry, and then double clicked into a sub-group to edit that,
the active_path might contain:
[<Sketchup::ComponentInstance>, <Sketchup::Group>]
Returns:
active_path = Sketchup.active_model.active_path
The active_view method returns the active View object for this model.
Returns:
model = Sketchup.active_model view = model.active_view
Add a text note to the Model. 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 1/10 of the ways down the screen from the upper left corner of the window.
Arguments:
Returns:
model = Sketchup.active_model # Add a note 1/10 ways down the screen and 1/10 ways right from the # upper left corner of model window. note = Sketchup.active_model.add_note "Hello World", 0.1, 0.1
The add_observer method is used to add an observer to the current object.
Arguments:
Returns:
model = Sketchup.active_model object = model.materials # We are adding a Material Observer here observer = Sketchup::MaterialsObserver.new status = object.add_observer observer
The attribute_dictionaries method retrieves the AttributeDictionaries object that is associated with the Model.
Returns:
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
Returns the Sketchup::AttributeDictionary object that is specified by name. If the model does not have an attribute dictionary that corresponds to name, returns either nil, or a creates an attribute dictionary. If the optional second argument is true, and there is no attribute dictionary that corresponds to name, a new attribute dictionary is created.
Arguments:
Returns:
model = Sketchup.active_model create_if_empty = true attributedictionary = model.attribute_dictionary "name", create_if_empty
The behavior method retrieves the behavior of the model.
Returns:
model = Sketchup.active_model behavior = model.behavior if (behavior) UI.messagebox behavior else UI.messagebox "Failure" end
The bounds method retrieves the bounding box of the model.
Returns:
model = Sketchup.active_model bounds = model.bounds if (bounds) length = bounds.depth 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.
Returns:
model = Sketchup.active_model status = model.close_active
The commit_operation method commits an operation for undo.
The commit_operation method is normally called at the end of a method to
commit the operation that the method performs.
Returns:
status = model.commit_operation
The definitions method retrieves a definition list containing all of the
component definitions in the model.
The returned definitions can be empty.
Returns:
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.
The returned description can be empty. The default description for all models
is empty.
Returns:
model = Sketchup.active_model desc = model.description
The description= method sets the description of the model.
If you do not include a description string, the description is cleared and
an empty description is returned.
Arguments:
Returns:
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"
Returns the transformation of the current component edit session. If a user has double-clicked to edit a component's geometry, this will return the transformation of that component, relative to its parent's origin. This allows one to correctly calculate "local" transformations of a given entity regardless of whether the user is in edit mode.
Returns:
Sketchup.active_model.edit_transform
The entities method returns an Entities object containing an array of
entities in the model.
If no entities are in your model, this method returns an empty Entities
object (an empty array)
Returns:
model = Sketchup.active_model entities = model.entities
The export method is used to export to the specified file format by
recognizing the given file extension and calling the appropriate exporter.
Optional second parameter show_summary dictates whether export summary
panel is shown after export operation. Returns true or false indicating
success or failure.
Arguments:
Returns:
model = Sketchup.active_model
show_summary = true
status = model.export "filename", show_summary
# Or for a COLLADA (.dae) file, using the default options
options_hash = { :triangulated_faces => true,
:doublesided_faces => true,
:edges => false,
:materials_by_layer => false,
:author_attribution => false,
:texture_maps => true,
:selectionset_only => false,
:preserve_instancing => true }
status = model.export "filename.dae", options_hashThis methods determines if the model is georeferenced.
if model.georeferenced?
UI.messagebox('This model is georeferenced.')
else
UI.messagebox('This model is NOT georeferenced.')
endThe get_attribute method gets the value of an attribute that in the AttributeDictionary with the given name. If no value is associated with key, or if the model does not have an attribute dictionary specified by name, the optional third parameter will be returned.
Arguments:
Returns:
model = Sketchup.active_model model.set_attribute "testdictionary", "test", 115 value = model.get_attribute "testdictionary", "test", 42
the get_datum method retrieves the datum, in the form of a string, used in UTM conversions.
Returns:
model = Sketchup.active_model datum = model.get_datum
Returns a constant number which indicates the product family of the installed SketchUp application. Meaning of the values are as follows:
Arguments:
Returns:
# Create a friendly array of product family names.
product_family_codes = []
product_family_codes[0] = 'Unknown'
product_family_codes[1] = 'Free'
product_family_codes[2] = 'Pro Evaluation Mode'
product_family_codes[3] = 'Pro License'
product_family_codes[4] = 'Pro Evaluation Expired'
product_family_codes[5] = 'Pro License Unavailable'
# Show a message of the current family.
current_product = Sketchup.active_model.get_product_family
UI.messagebox('You are running in ' + family_codes[current_product])The guid method retrieves the globally unique identifier, in the form of a string, for the Model.
Returns:
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.
Arguments:
Returns:
model = Sketchup.active_model show_summary = true status = model.import "filename", show_summary
The latlong_to_point method convert a latitude and longitude to a Point3d object in the model.
Returns:
latitude_longitude = [40.01700, 105.28300] model = Sketchup.active_model latlong = Geom::LatLong.new(latitude_longitude) point = model.latlong_to_point latlong
The layers method retrieves a collection of all Layers objects in the model.
Returns:
model = Sketchup.active_model layers = model.layers
This method retrieves an Array of all of the datums recognized by SketchUp.
Returns:
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.
Returns:
materials = model.materials
This method can be used to turn mipmapping on or off.
Arguments:
Returns:
# Turn off mipmapping Sketchup.active_model.mipmapping = false
This method can be used to find out if mipmapping is on or off.
Returns:
mipmapping_is_on = Sketchup.active_model.mipmapping?
The modified? method determines if the Model has been modified since the last save.
Returns:
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?
The name method retrieves the string name of the model.
Returns:
model = Sketchup.active_model name = model.name
The name= method sets the string name of the model.
Arguments:
Returns:
Sketchup.active_model.name = "My New Model Name"
Returns the number faces in a model.
f = model.number_faces puts 'There are ' + f.to_s + ' faces in the model.'
The options method retrieves the options manager that defines the options settings for the model.
Returns:
model = Sketchup.active_model
optionsmanager = model.options
if (optionsmanager)
# If an options manager is returned, iterate through each option
# provider within the options manager and display its name.
for option in optionsmanager
name = options.name
UI.messagebox name
end
else
UI.messagebox "Failure"
endThe pages method retrieves a Pages object containing all of the pages in the Model.
Returns:
model = Sketchup.active_model pages = model.pages
The path method retrieves the path of the file from which the model was
opened.
An empty string is returned for a new model (one which has not been saved
and opened.)
Returns:
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.
Arguments:
Returns:
status = model.placecomponent componentdefinition, repeat
The point_to_latlong method converts a point in the model to a LatLong so
that you can get its latitude and longitude.
This method uses the location information set in ShadowInfo.
NOTE: SketchUp 6.0 and higher has a change where this method returns a
Point3d instead of a LatLong, where the x and y values contain the LatLong
coordinates.
Arguments:
Returns:
model = Sketchup.active_model local_coordinates = [10,10,10] local_point = Geom::Point3d.new(coordinates) ll = model.point_to_latlong(local_point)
This method converts a Point3d object in the Model to UTM coordinates.
This method uses the location information set in ShadowInfo. See also UTM.
Arguments:
Returns:
model = Sketchup.active_model point = Geom::Point3d.new(10,10,10) utm = model.point_to_utm point
The raytest method is used to cast a ray (line) through the model and return
the first thing that the ray hits.
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. If direction can not be normalized
(e.g. direction = [0, 0, 0]), direction is taken as a point the ray
intersects.
Arguments:
Returns:
model = Sketchup.active_model ray = [Geom::Point3d.new(1,2,3), Geom::Vector3d.new(4,5,6)] item = model.raytest ray
The remove_observer method is used to remove an observer from the current object.
Arguments:
Returns:
model = Sketchup.active_model object = model.materials # Add a material observer observer = Sketchup::MaterialsObserver.new object.add_observer observer # Remove the material observer now status = object.remove_observer observer
The rendering_options method retrieves the RenderingOptions object for this Model.
Returns:
model = Sketchup.active_model renderingoptions = model.rendering_options
This method is used to save the model to a file.
Arguments:
Returns:
model = Sketchup.active_model status = model.save "mysketchup.skp"
The save_thumbnail method is used to save a thumbnail image to a file.
The image format is specified by the file extension of filename. Supported
formats are bmp, jpg, png, tif, pct, and gif.
Returns nil if it is an internal component.
Arguments:
Returns:
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
This method is used to select a SketchUp Tool object s the active tool. You
must implement the SketchUp Tool interface to create a tool prior to calling
this method.
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. If you attempt to set the select_tool to nil in the initialize
method of a tool you have written, it will be ignored.
Arguments:
Returns:
model = Sketchup.active_model tool = model.select_tool nil
This method retrieves a Selection object for the model, containing the currently selected entities. The entries in the selection list are not necessarily in the same order in which the user selected them.
Returns:
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.
This method can be used create a new AttributeDictionary object, if needed.
Arguments:
Returns:
model = Sketchup.active_model value = model.set_attribute "attributedictionaryname", "key", "value"
This method sets the datum used in conversions between the internal
coordinate system and UTM.
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.
Returns:
model = Sketchup.active_model value = model.set_datum "Adindan"
This method is used to retrieve the shadow information for the Model.
Returns:
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.
The String is a description for the operation that is displayed adjacent to
the Edit > Undo menu item.
Starting with SketchUp 7.0, there are three additional booleans that one can
pass in when starting an operation. All three default to false.
Arguments:
Returns:
model = Sketchup.active_model status = model.start_operation
The styles method retrieves the styles associated with the model.
Returns:
model = Sketchup.active_model styles = model.styles
The tags method retrieves the string tags of the model.
Returns:
model = Sketchup.active_model tags = model.tags
The tags= method sets the string tags of the model.
Arguments:
Returns:
Sketchup.active_model.tags = "Building, House, Brick"
The tile method retrieves the name of the model. If the model is saved on disk, returns the file name without extension. Otherwise returns an empty string.
Returns:
model = Sketchup.active_model title = model.title
The tools method is used to retrieve the current Tools object.
Returns:
model = Sketchup.active_model tools = model.tools
The utm_to_point method converts a position given in UTM coordinates to a Point3d in the Model.
Arguments:
Returns:
model = Sketchup.active_model utm = Geom::UTM.new [+1, "A", 0.12333333, 0.12321321] point = model.utm_to_point utm
Determine if a model is a valid Sketchup::Model object. Returns false
if the model has been closed.
This is useful on the mac where one can have multiple models open at the
same time. In such a case, this method can tell you if the user has closed
the model before you perform operations on it.
Returns:
# This is a silly example since the active model is generally going to
# be valid, but it illustrates the idea.
model = Sketchup.active_model
if model.valid?
UI.messagebox('This model is valid.')
else
UI.messagebox('This model is NOT valid.')
end