Class: Sketchup::InstancePath

Inherits:

Object

• Object
• Sketchup::InstancePath

Includes:

Enumerable

Overview

The InstancePath class represent the instance path to a given entity within the model hierarchy.

Version:

• SketchUp 2017

Instance Method Summary

• #==(other) ⇒ Boolean

  `true` if the instances paths represent the same set of entities.

• #[](index) ⇒ Sketchup::Entity

  The elements of an instance path can be accessed similarly to an array.

• #clear ⇒ Sketchup::InstancePath

  Clears the instance path.

• #clone ⇒ Sketchup::InstancePath

  Returns a new instance path with the same elements.

• #copy(other) ⇒ Sketchup::InstancePath

  Copies all elements from another instance path into this one.

• #each {|entity| ... } ⇒ nil

  The yielded entities will start with the root and end with the leaf.

• #empty? ⇒ Boolean
• #include?(object) ⇒ Boolean

  Returns `true` if the instance path contain the given object.

• #initialize(path) ⇒ Sketchup::InstancePath constructor
• #leaf ⇒ Sketchup::Entity^?

  The leaf of an instance path is the last element which can be any entity that can be represented in the model.

• #leaf=(entity) ⇒ Object

  Sets the leaf entity of the instance path.

• #length ⇒ Integer

  #length is an alias of #size.

• #persistent_id_path ⇒ String

  The serialized version of an instance path is the persistent ids of its entities concatenated with a period.

• #pop(*args) ⇒ Object

  Removes items from the end in-place.

• #push(entity) ⇒ Sketchup::InstancePath

  Appends the given entity to the path in-place.

• #root ⇒ Sketchup::Group, ...

  The root of an instance path is the element located closest to the model root.

• #size ⇒ Integer
• #to_a ⇒ Array

  An array representing the instance path.

• #transformation(*args) ⇒ Object
• #valid? ⇒ Boolean

  An instance path is valid if it has at least one element and consist of groups and instances with exception of the leaf which can be any entity.

Constructor Details

#initialize(path) ⇒ Sketchup::InstancePath

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])

Parameters:

• path (Array<Sketchup::Entity>) —

  The leaf can be any entity, but the rest must be a group or component instance.

Raises:

• (ArgumentError) —

  if the instance path isn't composed of instances and an optional leaf entity.

Version:

• SketchUp 2017

Instance Method Details

#==(other) ⇒ Boolean

Returns `true` if the instances paths represent the same set of entities.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.size > 1
  # do something
end

Returns:

• (Boolean) —

  `true` if the instances paths represent the same set of entities.

Version:

• SketchUp 2017

#[](index) ⇒ Sketchup::Entity

Note:

This method does not accept negative indices. For the exact behavior of an array, use {#to_a}.

The elements of an instance path can be accessed similarly to an array.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path[0] == group # returns true
path[1] == edge # returns true

Parameters:

• index (Integer)

Returns:

• (Sketchup::Entity)

Raises:

• (IndexError) —

  if the given index is out of bounds

• (TypeError) —

  if the index is not of integer type

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#clear ⇒ Sketchup::InstancePath

Clears the instance path.

This sets it to an empty state. After calling this, #valid? will return false and #empty? will return true.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.clear

Returns:

• (Sketchup::InstancePath) —

  self

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2026.2

#clone ⇒ Sketchup::InstancePath

Returns a new instance path with the same elements.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path1 = Sketchup::InstancePath.new([group, edge])
path2 = path1.clone

Returns:

• (Sketchup::InstancePath)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2026.2

#copy(other) ⇒ Sketchup::InstancePath

Copies all elements from another instance path into this one.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path1 = Sketchup::InstancePath.new([group, edge])
path2 = Sketchup::InstancePath.new([])
path2.copy(path1)

Parameters:

• other (Sketchup::InstancePath)

Returns:

• (Sketchup::InstancePath) —

  self

Raises:

• (TypeError) —

  if the given instance path refer to deleted entities.

Version:

• SketchUp 2026.2

#each {|entity| ... } ⇒ nil

The yielded entities will start with the root and end with the leaf.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.each { |entity|
  # do something
}

Yield Parameters:

• entity (Sketchup::Entity)

Returns:

• (nil)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#empty? ⇒ Boolean

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.empty?
  # do something...
end

Returns:

• (Boolean)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#include?(object) ⇒ Boolean

Returns `true` if the instance path contain the given object.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.include?(edge)
  # do something...
end

Parameters:

• object (Object)

Returns:

• (Boolean)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#leaf ⇒ Sketchup::Entity^?

The leaf of an instance path is the last element which can be any entity that can be represented in the model. This is normally a Drawingelement, but could be a Vertex.

An instance can also be a leaf.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.leaf == edge # returns true

Returns:

• (Sketchup::Entity, nil) —

  Nil if the last item of the instance path is a group or component, otherwise Entity.

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#leaf=(entity) ⇒ Object

Sets the leaf entity of the instance path.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group])
path.leaf = edge

Parameters:

• entity (Sketchup::Entity, nil)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

• (TypeError) —

  if the given entity is deleted.

Version:

• SketchUp 2026.2

#length ⇒ Integer

#length is an alias of #size.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.length > 1
  # do something
end

Returns:

• (Integer)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

See Also:

• #size

Version:

• SketchUp 2017

#persistent_id_path ⇒ String

The serialized version of an instance path is the persistent ids of its entities concatenated with a period.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
pid_path = path.persistent_id_path # something like "342.345"

Returns:

• (String)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

See Also:

• Model#instance_path_from_pid_path

Version:

• SketchUp 2017

#pop ⇒ Sketchup::Entity^? #pop(num) ⇒ Array<Sketchup::Entity>

Note:

If num is 0, no elements are removed. If num is greater than the path length, all elements are removed.

Removes items from the end in-place.

This treats the path as a flat list and removes items from the end, whether they are instances or a leaf.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
removed = path.pop # Returns edge

Overloads:

• #pop ⇒ Sketchup::Entity^?

  Returns the removed element or nil if the path is empty.

  Returns:

  • (Sketchup::Entity, nil) —

    the removed element or nil if the path is empty.

• #pop(num) ⇒ Array<Sketchup::Entity>

  Returns the removed elements.

  Parameters:

  • num (Integer) —

    the number of items to remove from the end.

  Returns:

  • (Array<Sketchup::Entity>) —

    the removed elements.

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

• (TypeError) —

  if the given num is not an integer.

• (ArgumentError) —

  if num is less than 0.

See Also:

• #push

Version:

• SketchUp 2026.2

#push(entity) ⇒ Sketchup::InstancePath

Note:

This method modifies the path in-place. Use #clone if you want to keep the original path unchanged.

Appends the given entity to the path in-place.

This treats the path as a flat list and appends the entity to the end. The entity can be an instance (group, component instance, image) or a leaf entity.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group])
path.push(edge) # path is now [group, edge]

Parameters:

• entity (Sketchup::Entity)

Returns:

• (Sketchup::InstancePath) —

  self

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

• (TypeError) —

  if the given entity is not a Sketchup::Entity.

• (ArgumentError) —

  if the resulting path would be invalid (e.g. adding an element after a leaf).

See Also:

• #pop

Version:

• SketchUp 2026.2

#root ⇒ Sketchup::Group, ...

The root of an instance path is the element located closest to the model root. This will be a group or component instance. If you have a non-instance as a leaf with no other parent component this will return `nil`.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
path.root == group # returns true

Returns:

• (Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#size ⇒ Integer

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.size > 1
  # do something
end

Returns:

• (Integer)

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

See Also:

• #length

Version:

• SketchUp 2017

#to_a ⇒ Array

Returns an array representing the instance path.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
pid_string = path.to_a.join('.')

Returns:

• (Array) —

  an array representing the instance path.

Raises:

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#transformation ⇒ Geom::Transformation #transformation(index) ⇒ Geom::Transformation

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
tr = path.transformation

Overloads:

• #transformation ⇒ Geom::Transformation

  Returns the combined transformation up to the the leaf entity.

  Returns:

  • (Geom::Transformation) —

    the combined transformation up to the the leaf entity.

• #transformation(index) ⇒ Geom::Transformation

  Returns the combined transformation up to the the given index.

  Parameters:

  • index (Integer)

  Returns:

  • (Geom::Transformation) —

    the combined transformation up to the the given index.

Raises:

• (IndexError) —

  if the given index is out of bounds

• (TypeError) —

  if the index is not of integer type

• (TypeError) —

  if the instance path refer to deleted entities.

Version:

• SketchUp 2017

#valid? ⇒ Boolean

An instance path is valid if it has at least one element and consist of groups and instances with exception of the leaf which can be any entity.

This method doesn't check if the path can actually be looked up in the model.

Examples:

model = Sketchup.active_model
group = model.entities.add_group
edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
path = Sketchup::InstancePath.new([group, edge])
if path.valid?
  # do something...
end

Returns:

• (Boolean)

Version:

• SketchUp 2017