Class: Sketchup::InstancePath

Relationships
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, Enumerable
Inherits:	Object

Overview

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

Version:

SketchUp 2017

Class Method Summary

.new(path) ⇒ Sketchup::InstancePath constructor

Instance Attribute Summary

#empty? ⇒ Boolean readonly
#leaf ⇒ Sketchup::Entity^? rw

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

Sets the leaf entity of the instance path.
#valid? ⇒ Boolean readonly

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.

Instance Method Summary

#==(other) ⇒ Boolean
#[](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.
#include?(object) ⇒ Boolean

Returns true if the instance path contain the given object.
#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 ⇒ Sketchup::Entity^?

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
#transformation ⇒ Geom::Transformation

Constructor Details

.new(path) ⇒ `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 Attribute Details

#empty? ⇒ `Boolean` (readonly)

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

Raises:

(TypeError) —
if the instance path refer to deleted entities.

Version:

SketchUp 2017

#leaf ⇒ Sketchup::Entity^? (rw)

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) (rw)

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

#valid? ⇒ `Boolean` (readonly)

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

Version:

SketchUp 2017

Instance Method Details

#==(other) ⇒ `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.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)

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 ⇒ `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:

(InstancePath) —
self

Raises:

(TypeError) —
if the instance path refer to deleted entities.

Version:

SketchUp 2026.2

#clone ⇒ `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

Raises:

(TypeError) —
if the instance path refer to deleted entities.

Version:

SketchUp 2026.2

#copy(other) ⇒ `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 (InstancePath)

Returns:

(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)

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)

Raises:

(TypeError) —
if the instance path refer to deleted entities.

Version:

SketchUp 2017

#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

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"

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:
- (Sketchup::Entity, nil) —
  the removed element or nil if the path is empty.
#pop(num) ⇒ Array<Sketchup::Entity>
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) ⇒ `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:

(InstancePath) —
self

Raises:

(TypeError) —
if the instance path refer to deleted entities.
(TypeError) —
if the given entity is not a Entity.
(ArgumentError) —
if the resulting path would be invalid (e.g. adding an element after a leaf).

See Also:

#pop

Version:

SketchUp 2026.2

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

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

Raises:

(TypeError) —
if the instance path refer to deleted entities.

See Also:

#length

Version:

SketchUp 2017

#to_a ⇒ 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])
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:
- (Geom::Transformation) —
  the combined transformation up to the the leaf entity.
#transformation(index) ⇒ Geom::Transformation
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

Class: Sketchup::InstancePath

Overview

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(path) ⇒ InstancePath

Instance Attribute Details

#empty? ⇒ Boolean (readonly)

#leaf ⇒ Sketchup::Entity? (rw)

#leaf=(entity) (rw)

#valid? ⇒ Boolean (readonly)

Instance Method Details

#==(other) ⇒ Boolean

#[](index) ⇒ Sketchup::Entity

#clear ⇒ InstancePath

#clone ⇒ InstancePath

#copy(other) ⇒ InstancePath

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

#include?(object) ⇒ Boolean

#length ⇒ Integer

#persistent_id_path ⇒ String

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

#push(entity) ⇒ InstancePath

#root ⇒ Sketchup::Group, ...

#size ⇒ Integer

#to_a ⇒ Array

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

.new(path) ⇒ `InstancePath`

#empty? ⇒ `Boolean` (readonly)

#leaf ⇒ Sketchup::Entity^? (rw)

#valid? ⇒ `Boolean` (readonly)

#==(other) ⇒ `Boolean`

#clear ⇒ `InstancePath`

#clone ⇒ `InstancePath`

#copy(other) ⇒ `InstancePath`

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

#include?(object) ⇒ `Boolean`

#length ⇒ `Integer`

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

#push(entity) ⇒ `InstancePath`

#size ⇒ `Integer`