class Sketchup::Image

An Image object represents a raster image placed in the Model.

@example Create material from image (SU 2018 and later)

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

Public Instance Methods

explode() click to toggle source

The explode method is used to explode an image into a face with a texture on it.

Note that current versions of SketchUp will return an empty array here. To work around this limitation you can iterate over your entities collection to determine which new entities were created.

Versions prior to SketchUp 2015 returned an empty array due to a bug.

@example

model = Sketchup.active_model
path = "Plugins/su_dynamiccomponents/images"
image_file = Sketchup.find_support_file("report_tool.png", path)
image = model.active_entities.add_image(image_file, ORIGIN, 300)
entities = image.explode

@return entitiesarray - an Array object of entities if

successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 39
def explode
end
glued_to() click to toggle source

The {#glued_to} method is used to retrieve the entity that this image is glued to.

@example

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

@return [Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil]

@version SketchUp 2021.1

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 57
def glued_to
end
glued_to=(drawing_element) click to toggle source

The {glued_to=} method glues this image to a drawing element. When moving this other drawing elment with the Move tool, the image moves with it.

@example

model = Sketchup.active_model
entities = model.active_entities

# Create a face
face = entities.add_face([[0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]])

# Create a group
path = "Plugins/su_dynamiccomponents/images"
image_file = Sketchup.find_support_file("report_tool.png", path)
image = model.active_entities.add_image(image_file, ORIGIN, 300)

# Glue the group to the face.
# If you now move the face, the group will follow.
image.glued_to = face

@param [Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil] drawing_element

@raise ArgumentError if this would lead to cyclic gluing.

@return [Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil] the entity the group was glued to.

@version SketchUp 2021.1

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 86
def glued_to=(drawing_element)
end
height() click to toggle source

The height method is used to retrieve the height of the image.

The height is given in inches.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
height = image.height
if (height)
  UI.messagebox height
else
  UI.messagebox "Failure"
end

@return height - the height of the model if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 109
def height
end
height=(height) click to toggle source

The height= method is used to set the height of the image.

The height is set in inches.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
UI.messagebox "Before adjustment"
height = image.height = 400
if (height)
  UI.messagebox height
else
  UI.messagebox "Failure"
end

@param height

The height, in inches, to set the image.

@return height - the new height if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 136
def height=(height)
end
image_rep() click to toggle source

The {#image_rep} method returns a copy of a {Sketchup::ImageRep} object representing the pixel data.

@bug Prior to SketchUp 2021.1, SketchUp crashes when the Image is corrupt and lacks image data.

@example

model = Sketchup.active_model
path = "Plugins/su_dynamiccomponents/images"
image_file = Sketchup.find_support_file("report_tool.png", path)
image = model.active_entities.add_image(image_file, ORIGIN, 300)
image_rep = image.image_rep

@raise ArgumentError if the Image is corrupt and lacks image data.

@return [Sketchup::ImageRep]

@version SketchUp 2018

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 156
def image_rep
end
normal() click to toggle source

The normal method is used to retrieve the 3D Vector that is perpendicular to the plane of the image.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
vector = image.normal
if (vector)
  UI.messagebox vector
else
  UI.messagebox "Failure"
end

@return vector - a Vector3d object if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 178
def normal
end
origin() click to toggle source

The origin method is used to retrieve the 3D point that defines the origin of the image.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
origin = image.origin
if (origin)
  UI.messagebox origin
else
  UI.messagebox "Failure"
end

@return point - a Point3d object containing the origin location

if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 201
def origin
end
origin=(point) click to toggle source

The origin= method is used to set the 3D point as the origin of the image.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
pt2 = Geom::Point3d.new 100,100,100
entities = model.active_entities
image = entities.add_image path, pt, 300
UI.messagebox "Before Move"
origin = image.origin=pt2
if (origin)
  UI.messagebox origin
else
  UI.messagebox "Failure"
end

@param point

A Point3d object with the new origin.

@return point - the Point3d object representing the newly

established origin if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 228
def origin=(point)
end
path() click to toggle source

The path method is used to retrieve the path of the file defining the image.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
path = image.path
if (path)
  UI.messagebox path
else
  UI.messagebox "Failure"
end

@return path - the path for the image file if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 249
def path
end
pixelheight() click to toggle source

The pixelheight method is used to retrieve the height of the image file in pixels.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
pixelheight = image.pixelheight
if (pixelheight)
  UI.messagebox pixelheight
else
  UI.messagebox "Failure"
end

@return height - the height of the image in pixels if

successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 272
def pixelheight
end
pixelwidth() click to toggle source

The pixelwidth method is used to retrieve the width of the image file in pixels.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
pixelwidth = image.pixelwidth
if (pixelwidth)
  UI.messagebox pixelwidth
else
  UI.messagebox "Failure"
end

@return width - the width of the image in pixels if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 294
def pixelwidth
end
size=(width, height) click to toggle source

The size= method is used to set the width and height of the image, in inches.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
UI.messagebox "Before Resize"
size = image.size= 500,500
if (size)
  UI.messagebox size
else
  UI.messagebox "Failure"
end

@param width

The width of the image.

@param height

The height of the image.

@return size - the new width and height of the image if

successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 323
def size=(width, height)
end
transform!(transform) click to toggle source

The transform! method is used to apply a transformation to the image.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
point = Geom::Point3d.new 100,100,100
t = Geom::Transformation.new point
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
UI.messagebox "Before Move"
image = image.transform! t
if (image)
  UI.messagebox image
else
  UI.messagebox "Failure"
end

@param transform

A Transformation object.

@return image - the transformed Image object if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 350
def transform!(transform)
end
transformation() click to toggle source

The transformation method is used to retrieve the transformation for the image.

@example

# Add an image to the model.
model = Sketchup.active_model
entities = model.active_entities
path = Sketchup.find_support_file('report_tool.png', 'Plugins/su_dynamiccomponents/images')
point = Geom::Point3d.new(100,100,100)
image = entities.add_image(path, point, 300)

trans = image.transformation

@return transformation - a Transformation object if successful

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 369
def transformation
end
transformation=(transform) click to toggle source

The transformation= method is used to set the transformation for the image.

@example

# Add an image to the model.
model = Sketchup.active_model
entities = model.active_entities
path = Sketchup.find_support_file('report_tool.png', 'Plugins/su_dynamiccomponents/images')
point = Geom::Point3d.new(100,100,100)
image = entities.add_image(path, point, 300)

new_transform = Geom::Transformation.new([100,0,0])
image.transformation = new_transform

@param transform

The Transformation object to apply

@return image - the newly transformed image

@version SketchUp 2014

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 392
def transformation=(transform)
end
width() click to toggle source

The width method is used to retrieve the width of the image.

The width is given in inches.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png",
  "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
width = image.width
if (width)
  UI.messagebox width
else
  UI.messagebox "Failure"
end

@return width - the width of the image if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 416
def width
end
width=(width) click to toggle source

The width= method is used to set the width of the image.

The width is set in inches.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
UI.messagebox "Before adjustment"
width = image.width=400
if (width)
  UI.messagebox width
else
  UI.messagebox "Failure"
end

@param width

The width, in inches, to set the image.

@return width - the new width if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 443
def width=(width)
end
zrotation() click to toggle source

The zrotation method is used to get the angle that the image is rotated about the normal vector from an arbitrary X axis.

@example

model = Sketchup.active_model
path = Sketchup.find_support_file "report_tool.png", "Tools/DynamicComponents/images"
pt = Geom::Point3d.new
entities = model.active_entities
image = entities.add_image path, pt, 300
zrotation = image.zrotation
if (zrotation)
  UI.messagebox zrotation
else
  UI.messagebox "Failure"
end

@return vector - a Vector3d object if successful

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Image.rb, line 465
def zrotation
end