Class: Sketchup::Model

Inherits:
Object
  • Object
show all
Defined in:
lib/sketchup-api-stubs/stubs/Sketchup/Model.rb

Overview

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.

Constants: Product Family

  • Model::ProTrial

  • Model::ProLicensed

  • Model::MakeTrial

  • Model::MakeTrialExpired

Examples:

# 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} materials.")

new_edge = entities.add_line([0,0,0], [500,500,0])

Version:

  • SketchUp 6.0

Constant Summary collapse

LOAD_STATUS_SUCCESS =

Constants

nil
LOAD_STATUS_SUCCESS_MORE_RECENT =

Stub value.

nil
Make =

Stub value.

nil
MakeTrial =

Stub value.

nil
ProLicensed =

Stub value.

nil
ProTrial =

Stub value.

nil
VERSION_2013 =

Stub value.

nil
VERSION_2014 =

Stub value.

nil
VERSION_2015 =

Stub value.

nil
VERSION_2016 =

Stub value.

nil
VERSION_2017 =

Stub value.

nil
VERSION_2018 =

Stub value.

nil
VERSION_2019 =

Stub value.

nil
VERSION_2020 =

Stub value.

nil
VERSION_2021 =

Stub value.

nil
VERSION_3 =

Stub value.

nil
VERSION_4 =

Stub value.

nil
VERSION_5 =

Stub value.

nil
VERSION_6 =

Stub value.

nil
VERSION_7 =

Stub value.

nil
VERSION_8 =

Stub value.

nil

Instance Method Summary collapse

Instance Method Details

#abort_operation ⇒ Boolean

Note:

Never abort a transparent operation. Doing so would abort the operation it chains to. Instead, try to clean up and simply commit in order to make sure the operation is closed.

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.

Examples:

status = model.abort_operation

Version:

  • SketchUp 6.0



89
90
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 89

def abort_operation
end

#active_entities ⇒ Sketchup::Entities

Returns an Entities object which contains the entities in the open group or component instance. If no group or component is open for editing then this will be the same as #entities.

To perform actions upon the current set of entities the user is working with then this is the method to use. Entities selected by the user will be a subset of the active entities.

Examples:

model = Sketchup.active_model
entities = model.active_entities
entities.each { |entity| puts "#{entity} (#{entity.class})" }

See Also:

Version:

  • SketchUp 6.0



110
111
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 110

def active_entities
end

#active_layer ⇒ Sketchup::Layer

The #active_layer method retrieves the active Layer.

The default layer in SketchUp is layer 0.

Examples:

model = Sketchup.active_model
layer = model.active_layer

Version:

  • SketchUp 6.0



124
125
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 124

def active_layer
end

#active_layer=(layer) ⇒ Sketchup::Layer

The #active_layer= method sets the active Layer object.

Examples:

model = Sketchup.active_model
layers = model.layers
layer = layers.add('My Layer')
model.active_layer = layer

Version:

  • SketchUp 6.0



141
142
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 141

def active_layer=(layer)
end

#active_path ⇒ Array<Sketchup::Drawingelement>?

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>]

Examples:

active_path = Sketchup.active_model.active_path

Version:

  • SketchUp 7.0



161
162
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 161

def active_path
end

#active_path=(instance_path) ⇒ Sketchup::Model

Note:

An instance path can only be opened if the instances are not locked. This also include instances of the same component definition that are not on the given path. A definition cannot be edited if any of its instances are locked.

Note:

Since changing the active entities in SketchUp also changes what coordinate system is used, entities can’t be modified in the same operation as the active entities changes. The API handles this automatically by starting and committing transparent operations as needed.

If the API user tries to do this:

model.start_operation('...', true)
model.active_entities.add_face(...)
model.active_path = instance_path
model.active_entities.add_face(...)
model.commit_operation

Then SketchUp will automatically break it up to something like to this:

model.start_operation('...', true)
model.active_entities.add_face(...)
model.commit_operation

model.start_operation('...', true, false, true)
model.active_path = instance_path
model.commit_operation

model.start_operation('...', true, false, true)
model.active_entities.add_face(...)
model.commit_operation

For the end user this will be experienced as a single operation.

For the API user the side-effect is multiple transaction notifications to Sketchup::ModelObservers.

The #active_path= method is used to open a given instance path for editing.

Examples:

Open an instance

model = Sketchup.active_model
instance = model.active_entities.grep(Sketchup::ComponentInstance).first
instance_path = Sketchup::InstancePath.new([instance])
model.active_path = instance_path

Close all instances

model = Sketchup.active_model
model.active_path = nil

Raises:

  • (ArgumentError) —

    if the instance path is not valid.

  • (ArgumentError) —

    if the instance path contains locked instances.

  • (ArgumentError) —

    if the instance path contains instances who’s siblings are locked.

  • (ArgumentError) —

    if the instance path contains Live Components.

Version:

  • SketchUp 2020.0



228
229
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 228

def active_path=(instance_path)
end

#active_view ⇒ Sketchup::View

The #active_view method returns the active View object for this model.

Examples:

model = Sketchup.active_model
view = model.active_view

Version:

  • SketchUp 6.0



240
241
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 240

def active_view
end

#add_note(note, x, y) ⇒ Sketchup::Text

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.

Examples:

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)

Version:

  • SketchUp 6.0



267
268
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 267

def add_note(note, x, y)
end

#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the current object.

Examples:

model = Sketchup.active_model
observer = Sketchup::ModelObserver.new
status = model.add_observer(observer)

Version:

  • SketchUp 6.0



283
284
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 283

def add_observer(observer)
end

#attribute_dictionaries ⇒ Sketchup::AttributeDictionaries

The #attribute_dictionaries method retrieves the AttributeDictionaries object that is associated with the Model.

Examples:

model = Sketchup.active_model
dictionaries = model.attribute_dictionaries
if dictionaries
  # 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

Version:

  • SketchUp 6.0



307
308
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 307

def attribute_dictionaries
end

#attribute_dictionary(name, create = false) ⇒ Sketchup::AttributeDictionary

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.

Examples:

model = Sketchup.active_model
create_if_empty = true
dictionary = model.attribute_dictionary('name', create_if_empty)

Version:

  • SketchUp 6.0



334
335
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 334

def attribute_dictionary(name, create = false)
end

#axes ⇒ Sketchup::Axes

The #axes method returns the drawing axes for the model.

Examples:

# Point for a rectangle.
points = [
  Geom::Point3d.new( 0,  0, 0),
  Geom::Point3d.new(10,  0, 0),
  Geom::Point3d.new(10, 20, 0),
  Geom::Point3d.new( 0, 20, 0)
]
# Transform the points so they are local to the model axes. Otherwise
# they would be local to the model origin.
tr = Sketchup.active_model.axes.transformation
points.each { |point| point.transform!(tr) }
Sketchup.active_model.active_entities.add_face(points)

Version:

  • SketchUp 2016



356
357
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 356

def axes
end

#behavior ⇒ Sketchup::Behavior

The behavior method retrieves the behavior of the model.

Examples:

model = Sketchup.active_model
behavior = model.behavior

Version:

  • SketchUp 6.0



368
369
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 368

def behavior
end

#bounds ⇒ Geom::BoundingBox

The #bounds method is used to retrieve the Geom::BoundingBox bounding the contents of a Sketchup::Model.

Examples:

model = Sketchup.active_model
bounds = model.bounds

Version:

  • SketchUp 6.0



381
382
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 381

def bounds
end

#classifications ⇒ Sketchup::Classifications

The #classifications method is used to retrieve the Classifications object for this model.

Examples:

model = Sketchup.active_model
c = model.classifications

Version:

  • SketchUp 2015



394
395
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 394

def classifications
end

#close(ignore_changes = false) ⇒ nil

The close method is used to close this model. On Mac OS, only the active model can be closed. On Windows, since there can be only one document open, this method will perform a File/New operation.

Examples:

Sketchup.file_new
model = Sketchup.active_model
model.close

Version:

  • SketchUp 2015



415
416
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 415

def close(ignore_changes = false)
end

#close_active ⇒ Boolean

Note:

Before SketchUp 2014 this method had a bug where it didn’t create an undo operation and that could lead to corrupted geometry when undo/redo was used after invoking this method.

The #close_active method is used to close the currently active (open) group or component.

Examples:

model = Sketchup.active_model
status = model.close_active

Version:

  • SketchUp 6.0



432
433
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 432

def close_active
end

#commit_operation ⇒ Boolean

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.

Examples:

status = model.commit_operation

Version:

  • SketchUp 6.0



446
447
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 446

def commit_operation
end

#definitions ⇒ Sketchup::DefinitionList

The #definitions method retrieves a definition list containing all of the component definitions in the model.

Examples:

model = Sketchup.active_model
definitions = model.definitions

Version:

  • SketchUp 6.0



459
460
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 459

def definitions
end

#description ⇒ String

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.

Examples:

model = Sketchup.active_model
description = model.description

Version:

  • SketchUp 6.0



475
476
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 475

def description
end

#description=(description) ⇒ String

The #description= method sets the description of the model.

Examples:

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"

Version:

  • SketchUp 6.0



491
492
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 491

def description=(description)
end

#drawing_element_visible?(instance_path) ⇒ Boolean

The #drawing_element_visible? method reports whether the given drawing element in an instance path is visible given the current model options.

Examples:

Traversing every visible entity in the model

module Example

  def self.instance?(entity)
    entity.is_a?(Sketchup::ComponentInstance) || entity.is_a?(Sketchup::Group)
  end

  # Walk the visible entities in the model, taking into account
  # "DrawHiddenGeometry" and "DrawHiddenObjects" rendering options.
  def self.walk(entities, transformation = IDENTITY, path = [], &block)
    entities.each { |entity|
      entity_path = path + [entity]
      next unless entity.model.drawing_element_visible?(entity_path)
      block.call(entity, transformation, path)
      if instance?(entity)
        child_entities = entity.definition.entities
        child_transformation = transformation * entity.transformation
        walk(child_entities, child_transformation, entity_path, &block)
      end
    }
  end

end

model = Sketchup.active_model
Example.walk(model.entities) do |entity, transformation, path|
  # Do something to every visible entity in the model...
end

Raises:

  • (ArgumentError) —

    if the instance_path is not valid.

See Also:

Version:

  • SketchUp 2020.0



539
540
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 539

def drawing_element_visible?(instance_path)
end

#edit_transform ⇒ Geom::Transformation

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.

Examples:

Sketchup.active_model.edit_transform

Version:

  • SketchUp 7.0



554
555
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 554

def edit_transform
end

#entities ⇒ Sketchup::Entities

Note:

This does not return a collection of all the entities in the model, only the top level node of the model hierarchy. To get to all entities in a model you must recursivly traverse the model.

The #entities method returns an Entities object containing the entities in the root of model.

Examples:

model = Sketchup.active_model
entities = model.entities

Version:

  • SketchUp 6.0



571
572
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 571

def entities
end

#export(path, show_summary = false) ⇒ Boolean #export(path, options) ⇒ Boolean

The export method is used to export a given file format. It knows which format to export based on the file extension you place on the file name. For example, a filename of “thing.obj” will export an OBJ file, whereas “thing.dae” will export a COLLADA file.

For SketchUp Pro 7.1+, valid extensions include dae, kmz, 3ds, dwg, dxf, fbx, obj, wrl, and xsi. SketchUp Free only supports dae and kmz.

Format Support Changes:

  • SketchUp 7.1 added COLLADA (.dae) export capability.

  • SketchUp Pro 2015+ added IFC export capability.

  • SketchUp Pro 2016+ added PDF export capability.

  • SketchUp Pro 2018+ added options for all 3D exporters.

See the Exporter Options file for information on creating a valid hash for the various exporters.

Examples:

General use

model = Sketchup.active_model
show_summary = true

# Export dwg file on a PC, showing a summary when complete.
status = model.export('c:\my_export.dwg', show_summary)

# Export kmz file on Mac (note the absolute file path), without summary.
status = model.export('/Library/my_export.kmz')

# Export pdf file on a PC, showing a summary when complete.
options_hash = { :show_summary => true,
                 :output_profile_lines => false,
                 :map_fonts => false,
                 :model_units => Length::Meter }
status = model.export('c:/my_export.pdf', options_hash)

# Or for a COLLADA (.dae) file.
options_hash = { :triangulated_faces => true,
                 :doublesided_faces => true,
                 :edges => false,
                 :author_attribution => false,
                 :texture_maps => true,
                 :selectionset_only => false,
                 :preserve_instancing => true }
status = model.export('c:/my_export.dae', options_hash)

IFC Example

model = Sketchup.active_model
# If no IFC types are passed in, then no geometry will be exported.
options_hash = { :hidden_geometry => true,
                 :ifc_mapped_items => true,
                 :ifc_types => ['IfcBuilding', 'IfcDoor']}
status = model.export('c:/my_export.ifc', options_hash)

Raises:

  • (ArgumentError) —

    If the file extension is unsupported.

Version:

  • SketchUp 6.0



641
642
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 641

def export(*args)
end

#find_entity_by_id(ids_or_array) ⇒ Array<Sketchup::Entity, nil>

Finds and returns entities by their entityID or GUID.

GUIDs looked up are only relevant to Group and ComponentInstance as these GUIDs are persistent. ComponentDefinition and Model GUIDs are not persistent and are not looked up.

When given an array of IDs, an array is returned with a 1:1 mapping to the input arguments. This array may contain nil values if some ids were not found. You cannot look up a mix of entityIDs and GUIDs in the same call.

Examples:

model = Sketchup.active_model

# Look up by entityID.
entity_id = model.entities.add_line([0,0,0], [9,9,9]).entityID
entity = model.find_entity_by_id(entity_id)

# Look up by GUID.
guid = model.entities.add_group.guid
entity = model.find_entity_by_id(guid)

# Look up multiple.
entities = model.find_entity_by_id(id1, id2, id3)
entities = model.find_entity_by_id([id1, id2, id3])
entities = model.find_entity_by_id(guid1, guid2, guid3)
entities = model.find_entity_by_id([guid1, guid2, guid3])

Version:

  • SketchUp 2015



681
682
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 681

def find_entity_by_id(ids_or_array)
end

#find_entity_by_persistent_id(ids_or_array) ⇒ Array<Sketchup::Entity, nil> #find_entity_by_persistent_id(ids_or_array, **scope) ⇒ Array<Sketchup::Entity, nil>

Finds and returns entities by their persistent id.

When given an array of IDs, an array is returned with a 1:1 mapping to the input arguments. This array may contain ‘nil` values if some ids were not found.

Examples:

model = Sketchup.active_model

# Look up by persistent_id.
pid = model.entities.add_line([0,0,0], [9,9,9]).persistent_id
entity = model.find_entity_by_persistent_id(pid)

# Look up multiple.
entities = model.find_entity_by_persistent_id(id1, id2, id3)
entities = model.find_entity_by_persistent_id([id1, id2, id3])

Limit search by scope

model = Sketchup.active_model
edge_pid = model.entities.add_line([0,0,0], [9,9,9]).persistent_id
layer_pid = model.layers.add('Hello World').persistent_id

# Search in all scopes:
entities = model.find_entity_by_persistent_id(edge_pid, layer_pid)
# => [#<Sketchup::Edge:0x000002567da4a8f0>, #<Sketchup::Layer:0x000002567da49e50>]

# Search in layer scope:
entities = model.find_entity_by_persistent_id(edge_pid, layer_pid, layers: true)
# => [nil, #<Sketchup::Layer:0x000002567da49e50>]

Overloads:

  • #find_entity_by_persistent_id(ids_or_array, **scope) ⇒ Array<Sketchup::Entity, nil>

    Returns an array with Entity objects for each id found and nil otherwise.

    Version:

    • SketchUp 2020.2

Version:

  • SketchUp 2017



748
749
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 748

def find_entity_by_persistent_id(*args)
end

#georeferenced? ⇒ Boolean

This methods determines if the model is georeferenced.

Examples:

if model.georeferenced?
  UI.messagebox('This model is georeferenced.')
else
  UI.messagebox('This model is NOT georeferenced.')
end

Version:

  • SketchUp 7.1



763
764
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 763

def georeferenced?
end

#get_attribute(dictname, key, defaultvalue = nil) ⇒ Object?

The 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.

Examples:

model = Sketchup.active_model
model.set_attribute('testdictionary', 'test', 115)
value = model.get_attribute('testdictionary', 'test', 42)

Version:

  • SketchUp 6.0



793
794
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 793

def get_attribute(dictname, key, defaultvalue = nil)
end

#get_datum ⇒ String

the get_datum method retrieves the datum, in the form of a string, used in UTM conversions.

Examples:

model = Sketchup.active_model
datum = model.get_datum

Version:

  • SketchUp 6.0



806
807
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 806

def get_datum
end

#get_product_family ⇒ Integer

Returns a value which indicates the product family of the installed SketchUp application. As of SketchUp 2013, the return values are:

  • 0 = Unknown

  • 1 = Pro Trial

  • 2 = Pro

  • 3 = Pro Expired

  • 4 = Make Trial

  • 5 = Make Expired

  • 6 = Make

  • 7 = Pro License Unavailable

The Model class defines some of these values as constants as of SketchUp 2016.

Examples:

model = Sketchup.active_model
product_family = model.get_product_family
if product_family == Sketchup::Model::ProLicensed then
  puts "You are running licensed SketchUp Pro!"
end

Version:

  • SketchUp 6.0



834
835
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 834

def get_product_family
end

#guid ⇒ String

The guid method retrieves the globally unique identifier, in the form of a string, for the Model. The guid will change after the model is modified and saved. The Model guid is stored with the SketchUp file; it will not change if the file is moved to another computer.

Examples:

model = Sketchup.active_model
guid = model.guid

Version:

  • SketchUp 6.0



850
851
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 850

def guid
end

#import(path, options) ⇒ Boolean #import(path, show_summary = false) ⇒ Boolean

The import method is used to load a file by recognizing the file extension and calling appropriate importer.

See DefinitionList#import for importing a 3d model file as a component definition, without activating the UI for placing an instance.

See the Importer Options file for information on creating a valid hash for the various importers.

Examples:

Import for SketchUp 2017 and older

model = Sketchup.active_model
show_summary = true
status = model.import("filename", show_summary)

Import for SketchUp 2018+ and newer

model = Sketchup.active_model
options = { :units => "model",
            :merge_coplanar_faces => true,
            :show_summary => true }
status = model.import("filename", options)

Overloads:

  • #import(path, show_summary = false) ⇒ Boolean
    Note:

    This variant is for SketchUp 2017 and earlier.

Version:

  • SketchUp 6.0



888
889
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 888

def import(*args)
end

#instance_path_from_pid_path(pid_path) ⇒ Sketchup::InstancePath

The #instance_path_from_pid_path method returns a instance path given a string with persistent ids representing the path to the entity.

Examples:

points = [
  Geom::Point3d.new( 0,  0, 0),
  Geom::Point3d.new(10,  0, 0),
  Geom::Point3d.new(10, 20, 0),
  Geom::Point3d.new( 0, 20, 0)
]
model = Sketchup.active_model
entities = model.active_entities
group = entities.add_group
face = group.entities.add_face(points)
pid_path = "#{group.persistent_id}.#{face.persistent_id}"
# pid_path will look something like this: "658.723"
instance_path = model.instance_path_from_pid_path(pid_path)

Raises:

  • (ArgumentError) —

    if a valid instance path cannot be created from the given input path string.

See Also:

Version:

  • SketchUp 2017



920
921
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 920

def instance_path_from_pid_path(pid_path)
end

#latlong_to_point(lnglat_array) ⇒ Geom::Point3d

The latlong_to_point method converts a latitude and longitude to a Point3d object in the model. It does not actually work with a LatLong object, but operates on a 2-element array. The returned point will always be on the ground (z=0).

Examples:

# Draw a point in Boulder, Colorado (40.0170N, 105.2830W)
lnglat_array = [-105.28300, 40.01700]
model = Sketchup.active_model
local_point = model.latlong_to_point(lnglat_array)
model.entities.add_cpoint(local_point)

Version:

  • SketchUp 6.0



943
944
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 943

def latlong_to_point(lnglat_array)
end

#layers ⇒ Sketchup::Layers

The #layers method retrieves a collection of all Layers objects in the model.

Examples:

model = Sketchup.active_model
layers = model.layers

Version:

  • SketchUp 6.0



957
958
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 957

def layers
end

#line_styles ⇒ Sketchup::LineStyles

The #line_styles method returns the line styles manager.

Examples:

line_styles = Sketchup.active_model.line_styles

Version:

  • SketchUp 2019



968
969
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 968

def line_styles
end

#list_datums ⇒ Array<String>

This method retrieves an Array of all of the datums recognized by SketchUp.

Examples:

model = Sketchup.active_model
datums = model.list_datums

Version:

  • SketchUp 6.0



981
982
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 981

def list_datums
end

#materials ⇒ Sketchup::Materials

The #materials method returns a collection of all of the materials in the model.

Examples:

model = Sketchup.active_model
materials = model.materials

Version:

  • SketchUp 6.0



994
995
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 994

def materials
end

#mipmapping=(mipmap) ⇒ Boolean

This method can be used to turn mipmapping on or off.

Examples:

Sketchup.active_model.mipmapping = false

Version:

  • SketchUp 7.0



1008
1009
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1008

def mipmapping=(mipmap)
end

#mipmapping? ⇒ Boolean

This method can be used to find out if mipmapping is on or off.

Examples:

mipmapping = Sketchup.active_model.mipmapping?

Version:

  • SketchUp 7.0



1019
1020
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1019

def mipmapping?
end

#modified? ⇒ Boolean

The modified? method determines if the Model has been modified since the last save.

Examples:

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?

Version:

  • SketchUp 6.0



1035
1036
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1035

def modified?
end

#name ⇒ String

The #name method retrieves the name of the model.

This property can be seen in Model Info and maps to the component name if the model is inserted into another model. This property should not be confused with the model #path.

Examples:

model = Sketchup.active_model
name = model.name

Version:

  • SketchUp 6.0



1051
1052
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1051

def name
end

#name=(name) ⇒ Object

The #name= method sets the string name of the model.

Examples:

Sketchup.active_model.name = "My New Model Name"

Version:

  • SketchUp 6.0



1062
1063
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1062

def name=(name)
end

#number_faces ⇒ Integer

Returns the number faces in a model.

Examples:

model = Sketchup.active_model
number_of_faces = model.number_faces
puts "There are #{number_of_faces} faces in the model."

Version:

  • SketchUp 7.1



1075
1076
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1075

def number_faces
end

#options ⇒ Sketchup::OptionsManager

The #options method retrieves the options manager that defines the options settings for the model.

Use the string keys instead of numerical indicies when accessing the options as the indicies are not consistent between SketchUp versions.

Examples:

# Output all options available.
options_manager = Sketchup.active_model.options
options_manager.each { |options_provider|
  puts options_provider.name
  options_provider.each { |key, value|
    puts "> #{key} - #{value}"
  }
}

Version:

  • SketchUp 6.0



1097
1098
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1097

def options
end

#overlays ⇒ Sketchup::OverlaysManager

Examples:

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
}

Version:

  • SketchUp 2023.0



1111
1112
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1111

def overlays
end

#pages ⇒ Sketchup::Pages

The #pages method retrieves a Pages object containing all of the pages in the model.

Examples:

model = Sketchup.active_model
pages = model.pages

Version:

  • SketchUp 6.0



1124
1125
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1124

def pages
end

#path ⇒ String

The path method retrieves the path of the file from which the model was opened.

An empty string is returned for a model that has not been saved.

Examples:

model = Sketchup.active_model
path = model.path

Version:

  • SketchUp 6.0



1139
1140
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1139

def path
end

#place_component(componentdef, repeat = false) ⇒ Sketchup::Model?

The place_component method places a new component in the Model using the component placement tool.

Examples:

model.place_component componentdefinition, repeat

Version:

  • SketchUp 6.0



1159
1160
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1159

def place_component(componentdef, repeat = false)
end

#point_to_latlong(point) ⇒ Geom::Point3d, Geom::LatLong

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.

Examples:

model = Sketchup.active_model
local_point = Geom::Point3d.new(10, 10, 10)
world_point = model.point_to_latlong(local_point)

Version:

  • SketchUp 6.0



1183
1184
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1183

def point_to_latlong(point)
end

#point_to_utm(point) ⇒ Geom::UTM

This method converts a Point3d object in the Model to UTM coordinates.

This method uses the location information set in ShadowInfo. See also UTM.

Examples:

model = Sketchup.active_model
point = Geom::Point3d.new(10, 10, 10)
utm = model.point_to_utm(point)

Version:

  • SketchUp 6.0



1201
1202
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1201

def point_to_utm(point)
end

#raytest(ray, wysiwyg_flag = true) ⇒ Array(Geom::Point3d, Array<Sketchup::Drawingelement>)?

Note:

The parameter wysiwyg_flag was added in SU8 M1.

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.

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 is 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,
Component3...].

Examples:

model = Sketchup.active_model
ray = [Geom::Point3d.new(1, 2, 3), Geom::Vector3d.new(4, 5, 6)]
item = model.raytest(ray, false) # Consider hidden geometry when
                                 # computing intersections.

Version:

  • SketchUp 6.0



1242
1243
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1242

def raytest(ray, wysiwyg_flag = true)
end

#remove_observer(observer) ⇒ Boolean

The remove_observer method is used to remove an observer from the current object.

Examples:

model = Sketchup.active_model
observer = Sketchup::ModelObserver.new
model.add_observer(observer)
status = model.remove_observer(observer)

Version:

  • SketchUp 6.0



1260
1261
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1260

def remove_observer(observer)
end

#rendering_options ⇒ Sketchup::RenderingOptions

The #rendering_options method retrieves the RenderingOptions object for this model.

Examples:

model = Sketchup.active_model
renderingoptions = model.rendering_options

Version:

  • SketchUp 6.0



1273
1274
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1273

def rendering_options
end

#save ⇒ Boolean #save(path) ⇒ Boolean #save(path, version) ⇒ Boolean

Note:

A bug in SketchUp 2016 and older caused the .skb backup file written during save to be empty. The .skp file was however valid.

Note:

Starting with SketchUp 2021, SketchUp is using a the same file format across versions. For instance, SketchUp 2021 can open a file made in SketchUp 2022.

This method is used to save the model to a file.

Examples:

model = Sketchup.active_model
# Save the model using the current SketchUp format
path = File.join(ENV['HOME'], 'Desktop', 'mysketchup.skp')
status = model.save(path)

# Save the model to the current file using the current SketchUp format
status = model.save

# Save the model to the current file in SketchUp 8 format
status = model.save("", Sketchup::Model::VERSION_8)

# Save the model in SketchUp 8 format
path = File.join(ENV['Home'], 'Desktop', 'mysketchup_v8.skp')
status = model.save(path, Sketchup::Model::VERSION_8)

Overloads:

  • #save ⇒ Boolean

    Save model to the path it is already associated with.

    Raises:

    • ArgumentError if the model is not previosly saved.

    Version:

    • SketchUp 2014

  • #save(path) ⇒ Boolean

    Save the model to a given path.

    Version:

    • SketchUp 6.0

  • #save(path, version) ⇒ Boolean

    Save the model as a specific SketchUp file version to a given path.

    Version:

    • SketchUp 2014



1337
1338
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1337

def save(*args)
end

#save_copy(path, version) ⇒ Boolean

This method is used to save the copy of the current model to a file.

Examples:

model = Sketchup.active_model
# Save copy of the model using the current SketchUp format
path = File.join(ENV['Home'], 'Desktop', 'myModelCopy.skp')
status = model.save_copy(path)

# Save copy of the model in SketchUp 8 format
path = File.join(ENV['Home'], 'Desktop', 'mysketchupcopy_v8.skp')
status = model.save_copy(path, Sketchup::Model::VERSION_8)

Version:

  • SketchUp 2014



1361
1362
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1361

def save_copy(path, version)
end

#save_thumbnail(filename) ⇒ Boolean

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.

Examples:

model = Sketchup.active_model
status = model.save_thumbnail('testthumbnail2.jpg')

Version:

  • SketchUp 6.0



1379
1380
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1379

def save_thumbnail(filename)
end

#select_tool(tool) ⇒ Sketchup::Model

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 activated 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.

Examples:

model = Sketchup.active_model
tool = model.select_tool(nil)

Version:

  • SketchUp 6.0



1402
1403
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1402

def select_tool(tool)
end

#selection ⇒ Sketchup::Selection

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.

Examples:

model = Sketchup.active_model
selection = model.selection

Version:

  • SketchUp 6.0



1417
1418
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1417

def selection
end

#set_attribute(attrdictname, key, value) ⇒ Object

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.

Examples:

model = Sketchup.active_model
value = model.set_attribute('attributedictionaryname', 'key', 'value')

Version:

  • SketchUp 6.0



1442
1443
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1442

def set_attribute(attrdictname, key, value)
end

#set_datum(datum) ⇒ nil

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.

Examples:

model = Sketchup.active_model
value = model.set_datum('Adindan')

Version:

  • SketchUp 6.0



1461
1462
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1461

def set_datum(datum)
end

#shadow_info ⇒ Sketchup::ShadowInfo

This method is used to retrieve the shadow information for the Model.

Examples:

model = Sketchup.active_model
shadowinfo = model.shadow_info

Version:

  • SketchUp 6.0



1473
1474
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1473

def shadow_info
end

#start_operation(op_name, disable_ui = false, next_transparent = false, transparent = false) ⇒ Boolean

Note:

Operations in SketchUp are sequential and cannot be nested. If you start a new Ruby operation while another is still open, you will implicitly close the first one.

The #start_operation method is used to notify SketchUp that a new operation (which can be undone) is starting.

The op_name argument is a description for the operation that is displayed adjacent to the Edit > Undo menu item. Make sure to provide a user friendly name for your operation.

Starting with SketchUp 7.0, there are three additional booleans that one can pass in when starting an operation. It is recommended to always set disable_ui to true. It’s left to false for default for compatibility reasons.

Examples:

Observer Operation since SU2016

class MyDefinitionsObserver < Sketchup::DefinitionObserver
  def onComponentAdded(definitions, definition)
    return if definition.deleted?
    # The operation name won't be displayed when the fourth argument is
    # +true+. It will absorb into the previous operation.
    definition.model.start_operation('Tag It', true, false, true)
    definition.set_attribute('MyExtension', 'Tag', 'You are it')
    definition.model.commit_operation
  end
end

observer = MyDefinitionsObserver.new
model = Sketchup.active_model
model.definitions.add_observer(observer)

Typical Operation

model = Sketchup.active_model
model.start_operation('Generate House', true)
model.entities.add_line([0, 0, 0], [9, 0, 0])
model.entities.add_line([9, 0, 0], [9, 0, 9])
model.commit_operation

Raises:

Version:

  • SketchUp 6.0



1544
1545
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1544

def start_operation(op_name, disable_ui = false, next_transparent = false, transparent = false)
end

#styles ⇒ Sketchup::Styles

The #styles method retrieves the styles associated with the model.

Examples:

model = Sketchup.active_model
styles = model.styles

Version:

  • SketchUp 6.0



1556
1557
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1556

def styles
end

#tags ⇒ String

The tags method retrieves the string tags of the model.

Examples:

model = Sketchup.active_model
tags = model.tags

Version:

  • SketchUp 6.0



1568
1569
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1568

def tags
end

#tags=(tags) ⇒ String

The tags= method sets the string tags of the model.

Examples:

Sketchup.active_model.tags = "Building, House, Brick"

Version:

  • SketchUp 6.0



1582
1583
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1582

def tags=(tags)
end

#title ⇒ String

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.

Examples:

model = Sketchup.active_model
title = model.title

Version:

  • SketchUp 6.0



1597
1598
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1597

def title
end

#tools ⇒ Sketchup::Tools

The #tools method is used to retrieve the current Tools object.

Examples:

model = Sketchup.active_model
tools = model.tools

Version:

  • SketchUp 6.0



1609
1610
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1609

def tools
end

#utm_to_point(utm) ⇒ Geom::Point3d

The utm_to_point method converts a position given in UTM coordinates to a Point3d in the Model.

Examples:

model = Sketchup.active_model
utm = Geom::UTM.new([+1, "A", 0.12333333, 0.12321321])
point = model.utm_to_point(utm)

Version:

  • SketchUp 6.0



1626
1627
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1626

def utm_to_point(utm)
end

#valid? ⇒ Boolean

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.

Examples:

# 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

Version:

  • SketchUp 6.0



1649
1650
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Model.rb', line 1649

def valid?
end