SketchUp Ruby API

https://ruby.sketchup.com
Admin
Comprehensive reference documentation for the Ruby API used to script and extend SketchUp, a...
Tokens:797,756
Snippets:8,685
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Overlay with start Method

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

Defines an ExampleOverlay with a start method that logs a message when the overlay becomes active.

```ruby
class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def start
    puts "Overlay #{self} started"
  end

end
```

--------------------------------

### Sketchup::Overlay#start

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

Abstract method to be implemented by subclasses to perform actions when the overlay starts.

```APIDOC
## Sketchup::Overlay#start

### Description
Abstract method to be implemented by subclasses to perform actions when the overlay starts.

### Returns
* (`Object`)
```

--------------------------------

### Get all picked entities using PickHelper

Source: https://ruby.sketchup.com/Sketchup/PickHelper.html

This example demonstrates how to use do_pick to perform an initial pick and then retrieve all entities within the pick paths using all_picked. Be aware that duplicates may occur if entities are nested within groups or components.

```ruby
ph = view.pick_helper
ph.do_pick(x, y)
entities = ph.all_picked
```

--------------------------------

### Sketchup::Image Overview and Example

Source: https://ruby.sketchup.com/Sketchup/Image.html

Provides an overview of the Sketchup::Image class and an example of how to create a material from an image.

```APIDOC
## Overview
An Image object represents a raster image placed in the Model.
#### Examples:
##### 
Create material from image (SU 2018 and later)
```ruby
model = Sketchup.active_model
entities = model.active_entities
image = entities.grep(Sketchup::Image).first
img_rep = image.image_rep
material = model.materials.add("New Name")
material.texture = img_rep
```

Version:
  * SketchUp 6.0
```

--------------------------------

### Implementing a Simple Animation

Source: https://ruby.sketchup.com/Sketchup/Animation.html

This example demonstrates how to implement a simple animation by creating a class that adheres to the Sketchup::Animation interface. It includes the required `nextFrame` method and the optional `stop` callback, along with code to add menu items for starting and stopping the animation.

```APIDOC
## Class: SimpleFloatAnimation

### Description
Implements a simple animation that moves the camera upward.

### Methods
#### `initialize`
Initializes the animation with a speed.

#### `nextFrame(view)`
Required method called for each animation frame. Moves the camera upward and returns `true` to continue the animation if the camera's Z position is less than 500.0, otherwise returns `false`.

#### `stop`
Optional callback method invoked by SketchUp when the animation is stopped. Prints a message indicating the animation was stopped.

### Example Usage
```ruby
# This example demonstrates a simple animation with implementation of
# the optional callback method stop, which is invoked
# by SketchUp during specific animation events.
class SimpleFloatAnimation
  def initialize
    @speed = 1.0           # Camera movement speed
    puts "Animation initialized"
  end

  # Required method - called for each animation frame
  def nextFrame(view)
    # Move camera upward
    new_eye = view.camera.eye
    new_eye.z = new_eye.z + @speed
    view.camera.set(new_eye, view.camera.target, view.camera.up)
    view.show_frame

    # Continue animation until reaching maximum height
    return new_eye.z < 500.0
  end

  # Optional callback - called by SketchUp when animation is stopped
  # Note: This method is called automatically by SketchUp and cannot
  # be called directly to stop an animation
  def stop
    puts "Animation was stopped by SketchUp"
    # Cleanup code when animation ends
  end
 end

 # Add menu item to start the animation
 UI.menu("Camera").add_item("Start Animation") {
   animation = SimpleFloatAnimation.new
   Sketchup.active_model.active_view.animation = animation
 }

 # To stop the animation programmatically:
 UI.menu("Camera").add_item("Stop Animation") {
   # Setting animation to nil will trigger the stop method in our animation class
   Sketchup.active_model.active_view.animation = nil
 }
```
```

--------------------------------

### Set Toolbar Visibility (PC Example)

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Examples of setting toolbar visibility to true on PC. Note that these specific calls were fixed.

```ruby
UI.set_toolbar_visible("Walkthrough", true)
```

--------------------------------

### Set Toolbar Visibility (PC Example)

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Examples of setting toolbar visibility to true on PC. Note that these specific calls were fixed.

```ruby
UI.set_toolbar_visible("FullToolSet", true)
```

--------------------------------

### Example ToolsObserver Implementation

Source: https://ruby.sketchup.com/Sketchup/ToolsObserver.html

This is an example of an observer that watches tool interactions. Attach the observer to the Sketchup.active_model.tools object.

```ruby
class MyToolsObserver < Sketchup::ToolsObserver
  def onActiveToolChanged(tools, tool_name, tool_id)
    puts "onActiveToolChanged: #{tool_name}"
  end
end

# Attach the observer.
Sketchup.active_model.tools.add_observer(MyToolsObserver.new)
```

--------------------------------

### Sketchup::Http::Request#start

Source: https://ruby.sketchup.com/Sketchup/Http/Request.html

Starts the HTTP request. Optionally accepts a response callback block that will be executed upon receiving a response from the server.

```APIDOC
## Sketchup::Http::Request#start

### Description
Starts the HTTP request. Optionally accepts a response callback block that will be executed upon receiving a response from the server.

### Method
`#start { |request, response| ... }`

### Parameters
* `request` (Sketchup::Http::Request) - The request object itself.
* `response` (Sketchup::Http::Response) - The response object received from the server.

### Returns
* `Boolean`

### Examples
```ruby
@request = Sketchup::Http::Request.new("http://localhost:8080")

@request.start do |request, response|
  puts "Status: #{response.status}"
  puts "Body: #{response.body}"
end
```
```

--------------------------------

### Implement a Simple Float Animation in Ruby

Source: https://ruby.sketchup.com/Sketchup/Animation.html

This example shows how to implement the required `nextFrame` and optional `stop` methods for a custom animation. It demonstrates moving the camera upwards and includes menu items to start and stop the animation.

```Ruby
class SimpleFloatAnimation
  def initialize
    @speed = 1.0           # Camera movement speed
    puts "Animation initialized"
  end

  # Required method - called for each animation frame
  def nextFrame(view)
    # Move camera upward
    new_eye = view.camera.eye
    new_eye.z = new_eye.z + @speed
    view.camera.set(new_eye, view.camera.target, view.camera.up)
    view.show_frame

    # Continue animation until reaching maximum height
    return new_eye.z < 500.0
  end

  # Optional callback - called by SketchUp when animation is stopped
  # Note: This method is called automatically by SketchUp and cannot
  # be called directly to stop an animation
  def stop
    puts "Animation was stopped by SketchUp"
    # Cleanup code when animation ends
  end
 end

 # Add menu item to start the animation
 UI.menu("Camera").add_item("Start Animation") {
   animation = SimpleFloatAnimation.new
   Sketchup.active_model.active_view.animation = animation
 }

 # To stop the animation programmatically:
 UI.menu("Camera").add_item("Stop Animation") {
   # Setting animation to nil will trigger the stop method in our animation class
   Sketchup.active_model.active_view.animation = nil
 }

```

--------------------------------

### Checking Load on Start Status

Source: https://ruby.sketchup.com/SketchupExtension.html

This snippet demonstrates how to check if an extension is configured to load automatically when SketchUp starts. It also shows how to register an extension to load on start.

```ruby
ext = SketchupExtension.new('Stair Tools', 'StairTools/core')
puts "load_on_start? is false: #{ext.load_on_start?.to_s}"
Sketchup.register_extension(ext, true)
puts "load_on_start? is now true: #{ext.load_on_start?.to_s}"
```

--------------------------------

### Observe Transaction Events

Source: https://ruby.sketchup.com/Sketchup/ModelObserver.html

This example demonstrates how to handle transaction start, commit, empty, and abort events. It highlights that all callbacks fire at commit time, not when operations occur, and shows how to differentiate between transactions that modify the model and those that do not.

```ruby
# This example demonstrates handling both empty and non-empty transactions,
# while also showing how the observer event queuing works.
# The key difference is that onTransactionCommit is called when the transaction
# contains model changes, while onTransactionEmpty is called when no changes were made.
#
# IMPORTANT: Remember that ALL callbacks fire at commit time, not when operations occur.

class TransactionObserver < Sketchup::ModelObserver

  # Called for any transaction, but remember this fires at commit time,
  # not when start_operation is actually called
  def onTransactionStart(model)
    puts "Transaction started callback fired: #{Time.now}"
    # We can't actually track when the transaction really started,
    # so we just record when the callback fired
    @callback_time = Time.now
  end

  # Called for transactions that modified the model
  # This fires immediately after onTransactionStart at commit time
  def onTransactionCommit(model)
    # We can only calculate time between callbacks, not actual operation time
    elapsed = Time.now - @callback_time
    puts "Transaction committed with changes (#{elapsed.round(3)}s after callback)"
    puts "Note: All callbacks fired at commit time, not during operations"
    handle_transaction_completion(model, :with_changes)
  end

  # Called for transactions that didn't modify the model
  # This fires immediately after onTransactionStart at commit time
  def onTransactionEmpty(model)
    # We can only calculate time between callbacks, not actual operation time
    elapsed = Time.now - @callback_time
    puts "Transaction committed with NO changes (#{elapsed.round(3)}s after callback)"
    puts "Note: All callbacks fired at commit time, not during operations"
    handle_transaction_completion(model, :empty)
  end

  # Common handler for both types of transaction completions
  def handle_transaction_completion(model, type)
    puts "Transaction complete (#{type}): #{Time.now}"
    # Perform actions needed for any completed transaction
    # (for example, updating UI, logging, etc.)
  end

  def onTransactionAbort(model)
    puts "Transaction aborted: #{Time.now}"
  end
end

# Attach the observer
observer = TransactionObserver.new
Sketchup.active_model.add_observer(observer)

# Demonstration of the queuing behavior
puts "DEMONSTRATION OF OBSERVER EVENT QUEUING:"
puts "1. Starting transaction at: #{Time.now}"
model = Sketchup.active_model
model.start_operation("Transaction Test", true)

# Notice that no observer callbacks fire at this point
puts "2. After start_operation - no callbacks fired yet: #{Time.now}"
puts "3. Now adding geometry..."
model.entities.add_line([0,0,0], [100,0,0])

# Still no observer callbacks
puts "4. After adding geometry - still no callbacks: #{Time.now}"
puts "5. Now committing transaction..."

# All observer events will fire when we commit
model.commit_operation

# The callbacks have now fired in sequence at commit time
puts "6. After commit_operation - ALL callbacks have now fired: #{Time.now}"
```

--------------------------------

### Install Extension from Archive

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Use Sketchup.install_from_archive to install an extension from a .rbz file.

```ruby
Sketchup.install_from_archive
```

--------------------------------

### Set Toolbar Visibility (PC Example)

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Examples of setting toolbar visibility to false on PC. Note that these specific calls were fixed.

```ruby
UI.set_toolbar_visible("FullToolSet", false)
```

--------------------------------

### Set Toolbar Visibility (PC Example)

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Examples of setting toolbar visibility to false on PC. Note that these specific calls were fixed.

```ruby
UI.set_toolbar_visible("Walkthrough", false)
```

--------------------------------

### start=

Source: https://ruby.sketchup.com/Sketchup/ConstructionLine.html

Sets the start point of a construction line, making its length finite at the start. Setting to nil makes the line infinite at the start.

```APIDOC
## start=

### Description
Sets the start point of a construction line, making its length finite at the start. Setting to nil makes the line infinite at the start.

### Method
`start=(point)` or `start=(nil)`

### Parameters
#### Path Parameters
- **point** (`Geom::Point3d` or `nil`) - The Point3d object to set for the start point of the construction line, or nil to make the start infinite.

### Returns
- **point** (`Object`) - A Point3d object if successful or nil.
```

--------------------------------

### start

Source: https://ruby.sketchup.com/Sketchup/ConstructionLine.html

Retrieves the starting point of a construction line. Returns nil if the line is infinite at the start.

```APIDOC
## start

### Description
Retrieves the starting point of a construction line. Returns nil if the line is infinite at the start.

### Method
`start`

### Returns
- **point** (`Object`) - The Point3d object representing the starting point of the construction line (if successful).
```

--------------------------------

### FrameChangeObserver for Scene Transition Logging

Source: https://ruby.sketchup.com/Sketchup/FrameChangeObserver.html

An example implementation of FrameChangeObserver that logs the start of an animation and the percentage of completion to the console. It also notes that `from_scene` may not be populated on PC.

```ruby
class MyFrameChangeObserver
  def frameChange(from_scene, to_scene, percent_done)
    if percent_done == 0.0
      puts "Animating to scene '#{to_scene.name}':"
    else
      puts format("% 7.2f %%",percent_done*100)
    end
  end
end
@id = Sketchup::Pages.add_frame_change_observer(MyFrameChangeObserver.new)
```

--------------------------------

### Handle InputPoint with Previous Point Inference

Source: https://ruby.sketchup.com/Sketchup/View.html

This example demonstrates how to get an InputPoint, potentially inferring from a previously picked point. It highlights the preference for initializing and reusing InputPoint objects with the `pick` method.

```ruby
class ExampleTool

  def onLButtonUp(flags, x, y, view)
    @picked_input = view.inputpoint(x, y)
  end

  def onMouseMove(flags, x, y, view)
    # Note: It is preferrable to initialize input points using
    # Sketchup::InputPoint.new in `initialize` and reuse them doing the
    # picking using the `pick` method.
    if @inputpoint
      @inputpoint = view.inputpoint(x, y, @picked_input)
    else
      @inputpoint = view.inputpoint(x, y)
    end
  end

 def draw(view)
   if @inputpoint
     @inputpoint.draw(view) if @inputpoint.display?
   else
     @picked_input.draw(view) if @picked_input.display?
   end
 end
end
```

--------------------------------

### Get ArcCurve Start Angle

Source: https://ruby.sketchup.com/Sketchup/ArcCurve.html

Retrieves the start angle of an arc in radians. The example demonstrates creating a quarter circle and then extracting its start angle.

```ruby
# Create a 1/4 circle, radius of 5, normal to the Z axis
center = Geom::Point3d.new 0, 0, -1
normal = Geom::Vector3d.new 0,0,1
xaxis = Geom::Vector3d.new 1,0,0
start_a = Math::PI/2
end_a = Math::PI
model = Sketchup.active_model
entities = model.entities
edgearray = entities.add_arc center, xaxis, normal, 5, start_a, end_a
edge = edgearray[0]
arccurve = edge.curve
start_angle = arccurve.start_angle
```

--------------------------------

### Check if Extension Loads on Start

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Use SketchupExtension#load_on_start? to determine if an extension is configured to load automatically when SketchUp starts.

```ruby
SketchupExtension#load_on_start?
```

--------------------------------

### Get Edge Start Vertex

Source: https://ruby.sketchup.com/Sketchup/Edge.html

Retrieves the Vertex object located at the start of the edge.

```ruby
edge = Sketchup.active_model.entities.add_line([0, 0, 0], [100, 100, 0])
vertex = edge.start
```

--------------------------------

### Get Construction Line Start Point

Source: https://ruby.sketchup.com/Sketchup/ConstructionLine.html

Retrieves the starting point of a construction line. Returns nil if the line is infinite at the start.

```ruby
model = Sketchup.active_model
entities = model.active_entities
point1 = Geom::Point3d.new(0,0,0)
point2 = Geom::Point3d.new(20,20,20)
constline = entities.add_cline(point1, point2)
startofline = constline.start
```

--------------------------------

### Initializing an Overlay with Description

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

This example shows how to initialize a custom overlay class, providing a unique ID, a display name, and a descriptive string for the UI.

```ruby
class ExampleOverlay < Sketchup::Overlay

  def initialize
    description = "A short sentence describing the overlay."
    super('example_inc.my_overlay', 'Example Overlay', description: description)
  end

end

overlay = ExampleOverlay.new
```

--------------------------------

### Get the best picked entity using PickHelper

Source: https://ruby.sketchup.com/Sketchup/PickHelper.html

This example shows how to perform an initial pick with do_pick and then retrieve the single 'best' entity that would have been selected by the native Select tool using best_picked. Ensure do_pick is called before best_picked.

```ruby
ph = view.pick_helper
ph.do_pick(x, y)
best_entity = ph.best_picked
```

--------------------------------

### Get Start Point of Layout::Path

Source: https://ruby.sketchup.com/Layout/Path.html

Retrieves the starting Geom::Point2d of the Layout::Path. The path must be initialized with a start point.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(2, 2)
path = Layout::Path.new(start_point, end_point)
# should be equal to start_point
start = path.start_point
```

--------------------------------

### start

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

This abstract method is called when the overlay becomes active. It is intended for implementing custom logic that should execute upon the overlay's activation, such as setting up resources or initial states.

```APIDOC
## start

### Description
This abstract method is called when the overlay becomes active. It is intended for implementing custom logic that should execute upon the overlay's activation, such as setting up resources or initial states.

### Method
`start`

### Examples
```ruby
class ExampleOverlay < Sketchup::Overlay
  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def start
    puts "Overlay #{self} started"
  end
end
```
```

--------------------------------

### Get Start Extent Point

Source: https://ruby.sketchup.com/Layout/LinearDimension.html

Retrieves the paper space coordinates for the start of the dimension line itself.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(5, 5)
height = 1.0
dim = Layout::LinearDimension.new(start_point, end_point, height)
start_ext_point = dim.start_extent_point
```

--------------------------------

### Creating a UI::Command with a Submenu

Source: https://ruby.sketchup.com/UI/Command.html

Shows how to create a UI::Command and add it to a newly created submenu. This example demonstrates adding a 'Tester' menu item that displays a 'Hello World' message box when clicked.

```ruby
UI.menu("Draw").add_separator

# Adds a Test submenu to the Draw menu where the Tester menu item appears
testmenu = UI.menu("Draw").add_submenu("Test")

# This menu item simply displays Hello World on the screen when clicked.
cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") }
testmenu.add_item cmd
```

--------------------------------

### Tool Activation Example

Source: https://ruby.sketchup.com/Sketchup/Tool.html

This method is called when the tool is selected. It's a suitable place for initializing tool state.

```ruby
def activate
  puts 'Your tool has been activated.'
end
```

--------------------------------

### Get Start Arrow of Layout::Path

Source: https://ruby.sketchup.com/Layout/Path.html

Retrieves the start arrow associated with a Layout::Path. This method may return nil if no start arrow is present.

```ruby
start_arrow = path.start_arrow
```

--------------------------------

### Sketchup::Importer Methods (Install)

Source: https://ruby.sketchup.com/method_list.html

Methods for installing SketchUp importers from archives.

```APIDOC
## install_from_archive Sketchup

### Description
Installs a SketchUp importer from an archive.

### Method
POST

### Endpoint
N/A (Class Method)
```

--------------------------------

### Get Component Definition GUID

Source: https://ruby.sketchup.com/Sketchup/ComponentDefinition.html

Retrieves the unique identifier (GUID) for the first component definition in the active model.

```ruby
componentdefinition = Sketchup.active_model.definitions[0]
guid = componentdefinition.guid
```

--------------------------------

### Example Overlay Initialization and onMouseLeave

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

Defines a basic ExampleOverlay class with initialization and an onMouseLeave event handler.

```ruby
class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def onMouseLeave(view)
    puts "onMouseLeave"
  end

end
```

--------------------------------

### Set Toolbar Visibility (Mac Example)

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Examples of setting toolbar visibility to true and false on Mac. Note that these specific calls were fixed.

```ruby
UI.set_toolbar_visible("SolidModelToolPaletteController", true)
```

```ruby
UI.set_toolbar_visible("SolidModelToolPaletteController", false)
```

--------------------------------

### Get Start Connection Point

Source: https://ruby.sketchup.com/Layout/LinearDimension.html

Retrieves the paper space coordinates for the start of the dimension's connection line.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(5, 5)
height = 1.0
dim = Layout::LinearDimension.new(start_point, end_point, height)
start_connection = dim.start_connection_point
```

--------------------------------

### start

Source: https://ruby.sketchup.com/Sketchup/Http/Request.html

Starts the HTTP request. An optional callback block can be provided to process the response once it is received. Do not cancel the request within the response callback.

```APIDOC
## start

### Description
Starts the request with optionally a response callback block. Do not cancel the request in the response callback.

### Method
`start`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
@request = Sketchup::Http::Request.new("http://localhost:8080")

@request.start do |request, response|
  puts "body: #{response.body}"
end
```

### Response
#### Success Response (200)
None explicitly documented, but the method returns a Boolean.

#### Response Example
None

### Yield Parameters
* request (`Sketchup::Http::Request`)
* response (`Sketchup::Http::Response`)

### Returns
* (`Boolean`)
```

--------------------------------

### Complete Custom Text Importer Example

Source: https://ruby.sketchup.com/Sketchup/Importer.html

This example demonstrates a full implementation of a custom importer for .txt files. It includes methods for setting the importer's description, file extension, unique ID, option support, handling options, and loading the file content.

```ruby
class TextImporter < Sketchup::Importer

  # This method is called by SketchUp to determine the description that
  # appears in the File > Import dialog's pulldown list of valid
  # importers.
  def description
    return "Custom Text Importer (*.txt)"
  end

  # This method is called by SketchUp to determine what file extension
  # is associated with your importer.
  def file_extension
    return "txt"
  end

  # This method is called by SketchUp to get a unique importer id.
  def id
    return "com.sketchup.importers.custom_txt"
  end

  # This method is called by SketchUp to determine if the "Options"
  # button inside the File > Import dialog should be enabled while your
  # importer is selected.
  def supports_options?
    return true
  end

  # This method is called by SketchUp when the user clicks on the
  # "Options" button inside the File > Import dialog. You can use it to
  # gather and store settings for your importer.
  def do_options
    # In a real use you would probably store this information in an
    # instance variable.
    my_settings = UI.inputbox(['My Import Option:'], ['1'],
      "Import Options")
  end

  # This method is called by SketchUp after the user has selected a file
  # to import. This is where you do the real work of opening and
  # processing the file.
  def load_file(file_path, status)
    # This where you do your import logic.

    return Sketchup::Importer::ImportSuccess
  end
end

Sketchup.register_importer(TextImporter.new)
```

--------------------------------

### Get Start Index of AutoTextDefinition

Source: https://ruby.sketchup.com/Layout/AutoTextDefinition.html

Retrieves the starting index for sequence-based auto-text definitions. This is useful for custom numbering sequences.

```ruby
doc = Layout::Document.open("C:/path/to/document.layout")
sequence_def = doc.auto_text_definitions.add("Seq1", Layout::AutoTextDefinition::TYPE_SEQUENCE)
start_index = sequence_def.start_index
```

--------------------------------

### Start Index Management

Source: https://ruby.sketchup.com/Layout/AutoTextDefinition.html

Methods for getting and setting the start index for page number, page count, and sequence AutoTextDefinitions.

```APIDOC
## start_index

### Description
The #start_index method returns the start index for `Layout::AutoTextDefinition::TYPE_PAGE_NUMBER`, `Layout::AutoTextDefinition::TYPE_PAGE_COUNT`, and `Layout::AutoTextDefinition::TYPE_SEQUENCE` AutoTextDefinitions.

### Method
Instance Method

### Response
#### Success Response (Integer)
- Returns the start index.
```

```APIDOC
## start_index=(index)

### Description
The #start_index= method sets the start index for `Layout::AutoTextDefinition::TYPE_PAGE_NUMBER`, `Layout::AutoTextDefinition::TYPE_PAGE_COUNT`, and `Layout::AutoTextDefinition::TYPE_SEQUENCE` AutoTextDefinitions.

### Method
Instance Method

### Parameters
#### Path Parameters
- **index** (Integer) - The start index to set.

### Response
#### Success Response (Object)
- Returns the object itself after setting the start index.
```

--------------------------------

### Get Start Extent Point of Angular Dimension

Source: https://ruby.sketchup.com/Layout/AngularDimension.html

Retrieves the paper space location for the start of the dimension line of an angular dimension.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(5, 5)
start_extent = Geom::Point2d.new(1, 2)
end_extent = Geom::Point2d.new(5, 6)
inner_angle = true
dim = Layout::AngularDimension.new(start_point, end_point, start_extent, end_extent,
  start_ext_point = dim.start_extent_point
```

--------------------------------

### Install Plugin from Archive

Source: https://ruby.sketchup.com/Sketchup.html

Installs the contents of a ZIP or RBZ archive file into SketchUp's Plugins folder, preserving directory structure. Handles potential user cancellation or installation errors.

```ruby
path = 'c:/temp/SomePluginPackage.zip'
begin
  Sketchup.install_from_archive(path)
rescue Interrupt => error
  puts "User said 'no': #{error}"
rescue Exception => error
  puts "Error during unzip: #{error}"
end
```

--------------------------------

### Get Dimension Start Point and Entity

Source: https://ruby.sketchup.com/Sketchup/DimensionLinear.html

Retrieves the start point of the dimension and the entity it references. Returns nil for the entity if none is attached.

```ruby
arr = dim.start
if arr[0].nil?
  puts "No attached entity. Point is #{arr[1]}"
else
  puts "Attached entity: #{arr[0]}, at point #{arr[1]}"
end
```

--------------------------------

### Initialize an InstancePath

Source: https://ruby.sketchup.com/Sketchup/InstancePath.html

Demonstrates how to create a new InstancePath object by providing an array of SketchUp entities. The path can include groups and component instances, with the leaf being any entity.

```ruby
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])
```

--------------------------------

### Creating and Displaying an Example Overlay

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

This snippet demonstrates how to create a custom overlay class that draws a blue rectangle and text in the viewport. It also shows how to use an AppObserver to automatically register this overlay when a new or opened model is active.

```ruby
class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def draw(view)
    rectangle = [
      [100, 100, 0], [300, 100, 0], [300, 200, 0], [100, 200, 0]
    ]
    view.drawing_color = 'blue'
    view.draw2d(GL_QUADS, rectangle)
    point = Geom::Point3d.new(120, 120, 0)
    view.draw_text(point, "Hello Overlay", size: 20, bold: true, color: 'white')
  end

end

# Using an observer to create a new overlay per model.
class ExampleAppObserver < Sketchup::AppObserver

  def expectsStartupModelNotifications
    true
  end

  def register_overlay(model)
    overlay = ExampleOverlay.new
    model.overlays.add(overlay)
  end
  alias_method :onNewModel, :register_overlay
  alias_method :onOpenModel, :register_overlay

end

observer = ExampleAppObserver.new
Sketchup.add_observer(observer)

# The following line is needed if you copy+paste in the Ruby Console or
# at the moment the extension is installed:
observer.register_overlay(Sketchup.active_model)
```

--------------------------------

### Get Start Offset Point of LinearDimension

Source: https://ruby.sketchup.com/Layout/LinearDimension.html

Retrieves the paper space location for the beginning of the first extension line. This point defines the start of the extension line segment leading to the start extent point.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(5, 5)
height = 1.0
dim = Layout::LinearDimension.new(start_point, end_point, height)
start_offset = dim.start_offset_point
```

--------------------------------

### Get a Specific Rendering Option Value

Source: https://ruby.sketchup.com/Sketchup/RenderingOptions.html

Use the `[]` method to retrieve the value of a specific rendering option by its key. For example, to get the 'DisplayInstanceAxes' setting.

```ruby
result = Sketchup.active_model.rendering_options["DisplayInstanceAxes"]
```

--------------------------------

### guid

Source: https://ruby.sketchup.com/Sketchup/ComponentInstance.html

Gets the base64 encoded unique identifier for this SketchUp object.

```APIDOC
## guid

### Description
The guid method is used to get the base 64 encoded unique id for this SketchUp object.

### Method
`guid`

### Returns
* String - The base64 encoded unique ID.
```

--------------------------------

### Sketchup::InstancePath Methods (Initialization)

Source: https://ruby.sketchup.com/method_list.html

Methods for initializing a Sketchup::InstancePath.

```APIDOC
## #initialize Sketchup::InstancePath

### Description
Initializes a new instance path.

### Method
POST

### Endpoint
N/A (Instance Method)
```

--------------------------------

### Sketchup::Overlay#initialize

Source: https://ruby.sketchup.com/Sketchup/Overlay.html

Initializes a new Overlay instance. This is the constructor for creating custom overlays.

```APIDOC
## Sketchup::Overlay#initialize

### Description
Initializes a new Overlay instance.

### Parameters
* **id** (String) - The string should be unique per overlay subclass. A good pattern would be something like: `“company_name.extension_name.overlay_name”`.
* **name** (String) - This is a user facing display name that will appear in the UI. Make it short and representative for what the overlay does.
* **description** (String) _(defaults to: "")_ - This is a user facing description that will appear in the UI. Make it short and representative for what the overlay does.

### Raises
* (`ArgumentError`) - if `id` or `name` is an empty string

### Examples:
```ruby
class ExampleOverlay < Sketchup::Overlay

  def initialize
    description = "A short sentence describing the overlay."
    super('example_inc.my_overlay', 'Example Overlay', description: description)
  end

end

overlay = ExampleOverlay.new
```
```

--------------------------------

### Retrieve Model's Globally Unique Identifier (GUID)

Source: https://ruby.sketchup.com/Sketchup/Model.html

Gets the unique string identifier for the model. This GUID is stored with the file and can change upon saving.

```ruby
model = Sketchup.active_model
guid = model.guid
```

--------------------------------

### Get Start Page of AutoTextDefinition

Source: https://ruby.sketchup.com/Layout/AutoTextDefinition.html

Retrieves the starting page for page number or page count auto-text definitions. The default is the document's first page.

```ruby
doc = Layout::Document.open("C:/path/to/document.layout")
page_number_def =
    doc.auto_text_definitions.add("PageNumber", Layout::AutoTextDefinition::TYPE_PAGE_NUMBER)
# Default start page is the first page of the document. However we continue to start at that
# page even if that page is moved.
page = page_number_def.start_page
p page == doc.pages[0]
doc.pages.add('new page')
doc.pages.reorder(doc.pages[0], 1)
p page == doc.pages[1]
```

--------------------------------

### Get Attached Start Point of Dimension

Source: https://ruby.sketchup.com/Sketchup/DimensionLinear.html

Retrieves the attached start point of a dimension, which is part of a component instance. Returns an array containing the InstancePath and the Geom::Point3d.

```ruby
# Assuming you have a valid dimension selected that is attached to a
# component instance
dim = Sketchup.active_model.selection[0]
dim.start_attached_to
```

--------------------------------

### Example Observer for New Models

Source: https://ruby.sketchup.com/Sketchup/AppObserver.html

This example demonstrates how to create an observer that reacts to new models being created. It also shows how to attach other observers, such as a SelectionObserver, to the newly created model.

```ruby
class MyAppObserver < Sketchup::AppObserver
  def onNewModel(model)
    puts "onNewModel: #{model}"

    # Here is where one might attach other observers to the new model.
    model.selection.add_observer(MySelectionObserver.new)
  end
end

# Attach the observer
Sketchup.add_observer(MyAppObserver.new)
```

--------------------------------

### Set Toolbar Visibility (Mac Example)

Source: https://ruby.sketchup.com/file.ReleaseNotes.html

Examples of setting toolbar visibility to false on Mac. Note that these specific calls were fixed.

```ruby
UI.set_toolbar_visible('GoogleToolPaletteController', false)
```

```ruby
UI.set_toolbar_visible('ToolPaletteController', false)
```

--------------------------------

### Start HTTP Request with Response Callback

Source: https://ruby.sketchup.com/Sketchup/Http/Request.html

Starts an HTTP request and optionally accepts a response callback block. Do not cancel the request within the response callback.

```ruby
@request = Sketchup::Http::Request.new("http://localhost:8080")

@request.start do |request, response|
  puts "body: #{response.body}"
end
```

--------------------------------

### Get the start vertex normal for an EdgeUse

Source: https://ruby.sketchup.com/Sketchup/EdgeUse.html

Retrieves the Geom::Vector3d representing the normal at the start vertex of this EdgeUse. This is useful for geometric analysis and understanding vertex orientation.

```ruby
entities = Sketchup.active_model.active_entities
points = []
points << Geom::Point3d.new(0, 0, 0)
points << Geom::Point3d.new(100, 0, 0)
points << Geom::Point3d.new(100, 200, 0)
points << Geom::Point3d.new(0, 200, 0)
face = entities.add_face(points)
loop = face.outer_loop
edgeuses = loop.edgeuses
edgeuse = edgeuses[0]
vector3d = edgeuse.start_vertex_normal
```

--------------------------------

### Create and Register an Extension (Alternative)

Source: https://ruby.sketchup.com/SketchupExtension.html

This example shows an alternative way to create and register a SketchupExtension, emphasizing the registration step for the extension to appear in the Extension Manager. Passing 'true' as the second argument to Sketchup.register_extension enables default loading.

```ruby
# Create an entry in the Extension list that loads a script called
# core.
extension = SketchupExtension.new('Stair Tools', 'StairTools/core')

# Then be sure to register it. By passing a 2nd param of true, you're
# telling SketchUp to load the extension by default.
Sketchup.register_extension(extension, true)
```

--------------------------------

### Get Start Offset Point

Source: https://ruby.sketchup.com/Layout/AngularDimension.html

Retrieves the paper space location for the start of the first extension line. This point defines the beginning of the first extension line, which connects to the start extent point. This method returns a Geom::Point2d object.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(5, 5)
start_extent = Geom::Point2d.new(1, 2)
end_extent = Geom::Point2d.new(5, 6)
inner_angle = true
dim = Layout::AngularDimension.new(start_point, end_point, start_extent, end_extent,
inner_angle)
start_offset = dim.start_offset_point
```

--------------------------------

### SketchupExtension#load_on_start?

Source: https://ruby.sketchup.com/SketchupExtension.html

Checks if the extension is configured to load automatically when SketchUp starts.

```APIDOC
## SketchupExtension#load_on_start?

### Description
Checks if the extension is configured to load automatically when SketchUp starts.

### Returns
* (`Boolean`)

### Version
* SketchUp 8.0 M2
```

--------------------------------

### Get Start Arrow Type from Layout Style

Source: https://ruby.sketchup.com/Layout/Style.html

Retrieve the type of the start arrow from a Layout::Style. Returns nil if no value is set. A comprehensive list of arrow types is available in the documentation.

```ruby
doc = Layout::Document.open("C:/path/to/document.layout")
page = doc.pages.first
entity = page.entities.first
style = entity.style
arrow_type = style.start_arrow_type
```

--------------------------------

### initialize

Source: https://ruby.sketchup.com/UI/WebDialog.html

Constructor for creating a new UI::WebDialog object. Accepts optional arguments for initialization.

```APIDOC
## initialize(*args)

### Description
Creates a new web dialog.

### Method
initialize

### Parameters
* **args** - Optional arguments for initialization.

### Returns
Object - A new UI::WebDialog instance.
```

--------------------------------

### Get Entity Glued To

Source: https://ruby.sketchup.com/Sketchup/Image.html

Retrieves the entity that this image is currently glued to. This is available starting from SketchUp 2021.1.

```ruby
point = Geom::Point3d.new(10, 20, 30)
transform = Geom::Transformation.new(point)
model = Sketchup.active_model
entities = model.active_entities
group = entities.add_group
group.entities.add_face([[0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0]])
status = group.glued_to
```

--------------------------------

### Get Edge Vertices

Source: https://ruby.sketchup.com/Sketchup/Edge.html

Retrieves an array containing the Vertex objects that define the start and end points of the edge.

```ruby
edge = Sketchup.active_model.entities.add_line([0, 0, 0], [100, 100, 0])
vertices = edge.vertices
```

--------------------------------

### Initialize Layout::SketchUpModel

Source: https://ruby.sketchup.com/Layout/SketchUpModel.html

Creates a new Layout::SketchUpModel instance. Requires the path to a .skp file and a Geom::Bounds2d object. The path must point to a valid SketchUp model, and the bounds must not be zero-sized.

```ruby
bounds = Geom::Bounds2d.new(1, 1, 3, 3)
model = Layout::SketchUpModel.new("C:/Path/to/model.skp", bounds)
```

--------------------------------

### Get Dimension Text

Source: https://ruby.sketchup.com/Sketchup/Dimension.html

Retrieves the current text displayed by the dimension. This method is available starting from SketchUp 2014.

```ruby
dimtext = dim.text
```

--------------------------------

### Create a Layout::Label

Source: https://ruby.sketchup.com/Layout/Label.html

Demonstrates how to initialize a new Layout::Label object with text, leader line type, target point, and bounds.

```ruby
text = "A label"
leader_type = Layout::Label::LEADER_LINE_TYPE_BEZIER
target_point = Geom::Point2d.new(1, 1)
bounds = Geom::Bounds2d.new(2, 1, 1, 1)
label_from_bounds = Layout::Label.new(text, leader_type, target_point,
  bounds)
leader = label_from_bounds.leader_line
```

--------------------------------

### Initialize WebDialog with Parameters

Source: https://ruby.sketchup.com/UI/WebDialog.html

Creates a new UI::WebDialog instance with specified title, dimensions, and positioning. The dialog's size and position are DPI aware on newer SketchUp versions.

```ruby
dlg = UI::WebDialog.new("Show sketchup.com", true,
  "ShowSketchupDotCom", 739, 641, 150, 150, true)
dlg.set_url "https://www.sketchup.com"
dlg.show
```

--------------------------------

### Get Point at Index from Polygon Mesh

Source: https://ruby.sketchup.com/Geom/PolygonMesh.html

Retrieves a point from the mesh using its index. Index starts at 1.

```ruby
mesh = Geom::PolygonMesh.new
point1 = Geom::Point3d.new(0, 1, 2)
point2 = Geom::Point3d.new(10, 20, 30)
mesh.add_point(point1)
mesh.add_point(point2)
point_from_index = mesh.point_at(1)
```

--------------------------------

### Retrieving Load Error

Source: https://ruby.sketchup.com/SketchupExtension.html

This example shows how to get the specific exception that occurred if an extension failed to load. This is useful for debugging.

```ruby
# broken/broken_file.rb
raise "This file raises an exception"

# broken.rb
extension = SketchupExtension.new("Broken Extension", "broken/broken_file")
extension.version = "1.0.0"
extension.description = "This extension's has an error."
Sketchup.register_extension(extension, true)

extension.load_error
# => RuntimeError
```

--------------------------------

### Creating and Picking an InputPoint

Source: https://ruby.sketchup.com/Sketchup/InputPoint.html

Demonstrates creating an InputPoint from screen coordinates and from a 3D point, and then using the pick method to associate it with the view. The pick method can optionally use another InputPoint for additional inferences.

```ruby
view = Sketchup.active_model.active_view
x = 100 # Screen coordinate
y = 200 # Screen coordinate
inputpoint = view.inputpoint(x, y)
inputpoint2 = Sketchup::InputPoint.new(Geom::Point3d.new(100, 250, 300))
inputpoint.pick(view, x, y)
inputpoint.pick(view, x, y, inputpoint2)
```

--------------------------------

### Get Active View in Sketchup

Source: https://ruby.sketchup.com/Sketchup/View.html

Retrieves the currently active view in the SketchUp model. This is a common starting point for interacting with the view.

```ruby
view = Sketchup.active_model.active_view
```

--------------------------------

### Cross-Platform Text Rendering in SketchUp

Source: https://ruby.sketchup.com/Sketchup/View.html

This example demonstrates how to draw text with consistent size across Windows and macOS by converting pixel sizes to points on Windows. It uses a helper method to handle platform-specific size conversions.

```ruby
class ExampleTool
  IS_WIN = Sketchup.platform == :platform_win

  def draw(view)
    draw_text(view, [100, 200, 0], "Hello World", size: 20)
  end

  private

  # This will ensure text is drawn with consistent size across platforms,
  # using pixels as size units.
  def draw_text(view, position, text, **options)
    native_options = options.dup
    if IS_WIN && options.key?(:size)
      native_options[:size] = pixels_to_points(options[:size])
    end
    view.draw_text(position, text, **native_options)
  end

  def pixels_to_points(pixels)
    ((pixels.to_f / 96.0) * 72.0).round
  end
end
```

--------------------------------

### Open Document and Get Pages

Source: https://ruby.sketchup.com/Layout/Pages.html

Opens a Layout document and retrieves all its pages. This is a common starting point for manipulating document pages.

```ruby
doc = Layout::Document.open("C:/path/to/document.layout")
pages = doc.pages
num_pages = pages.length
```

--------------------------------

### Create a Cube using Sketchup::Entities#add_face and pushpull

Source: https://ruby.sketchup.com/file.generating_geometry.html

Demonstrates creating a cube by adding a face and then using the pushpull method. This is useful for generating simple 3D shapes.

```ruby
module Example

  # @example
  #   Example.create_cube
  #
  def self.create_cube
    model = Sketchup.active_model
    model.start_operation('Create Cube', true)
    group = model.active_entities.add_group
    entities = group.entities
    points = [
      Geom::Point3d.new(0,   0,   0),
      Geom::Point3d.new(1.m, 0,   0),
      Geom::Point3d.new(1.m, 1.m, 0),
      Geom::Point3d.new(0,   1.m, 0)
    ]
    face = entities.add_face(points)
    face.pushpull(-1.m)
    model.commit_operation
  end

end
```

--------------------------------

### Get Start Connection Point of Angular Dimension

Source: https://ruby.sketchup.com/Layout/AngularDimension.html

Retrieves the paper space location for the first connection point of an angular dimension.

```ruby
start_point = Geom::Point2d.new(1, 1)
end_point = Geom::Point2d.new(5, 5)
start_extent = Geom::Point2d.new(1, 2)
end_extent = Geom::Point2d.new(5, 6)
inner_angle = true
dim = Layout::AngularDimension.new(start_point, end_point, start_extent, end_extent,
  start_connection = dim.start_connection_point
```

--------------------------------

### init

Source: https://ruby.sketchup.com/Sketchup/PickHelper.html

The #init method is used to initialize the PickHelper for testing points.

```APIDOC
## init

### Description
Initializes the `PickHelper` instance. This is typically used for testing points or setting up the helper for subsequent picking operations.

### Method
`init(*args)`

### Parameters
- `*args` - Arguments may vary depending on the initialization context.

### Returns
- `Sketchup::PickHelper` - The initialized `PickHelper` instance.

### Example
```ruby
ph = Sketchup::PickHelper.new
ph.init
```
```

--------------------------------

### Initialize and Start an HTTP Request

Source: https://ruby.sketchup.com/Sketchup/Http/Request.html

Initializes a new HTTP request and starts it with a callback to process the response. Ensure a reference to the request object is maintained to prevent silent download failures.

```ruby
@request = Sketchup::Http::Request.new("http://localhost:8080", Sketchup::Http::GET)

@request.start do |request, response|
  puts "body: #{response.body}"
end
```

--------------------------------

### Get the Unique ID of a Group

Source: https://ruby.sketchup.com/Sketchup/Group.html

Retrieves the base64 encoded unique identifier for a SketchUp group. This method is available starting from SketchUp 2014.

```ruby
# Add a group to the model.
group = Sketchup.active_model.entities.add_group
group.entities.add_line([0,0,0],[100,100,100])
guid = group.guid
```

--------------------------------

### Get Dimension Offset Vector

Source: https://ruby.sketchup.com/Sketchup/DimensionLinear.html

Retrieves the vector that defines the parallel offset from the reference line to the dimension line, measured from the start point.

```ruby
vec = dim.offset_vector
puts "Offset vector is #{vec.to_s}"
```

--------------------------------

### Instance Method: initialize (constructor)

Source: https://ruby.sketchup.com/Geom/Vector3d.html

Creates a new vector. Accepts a variable number of arguments to define the vector's components.

```APIDOC
## Constructor: .new

### Description
Creates a new vector. Accepts a variable number of arguments to define the vector's components.

### Method
`Geom::Vector3d.new(*args)`

### Parameters
* `*args`: Arguments to define the vector's components (e.g., x, y, z coordinates, or another vector/array).

### Returns
* Geom::Vector3d: A new Vector3d object.
```
Tokens:
Raw