123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::Material

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Entity
Instance Chain:
self, Comparable, Entity
Inherits: Sketchup::Entity

Overview

The Material class represents a Texture or Color that can be applied to Drawingelements. It is most often applied to Faces.

You can pass any object that can be used as a material to a method that requires a material. Objects include actual Material, Color, and classes that can be converted to a color.

Examples:

model = Sketchup.active_model
face = model.entities.add_face([0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0])
material = model.materials.add('Example')
# The following will all assign a red material to the face:
material.color = Sketchup::Color.new(255, 0, 0)
face.material = material
face.material = Sketchup::Color.new(255, 0, 0)
face.material = [255, 0, 0]
face.material = "red"
face.material = 0xff0000

Version:

  • SketchUp 6.0

Constant Summary

Instance Attribute Summary

Entity - Inherited

#deleted?

The deleted? method is used to determine if your entity is still valid (not deleted by another script, for example.).
#valid?

The #valid? method is used to determine if your entity is still valid (not deleted by another script, for example).

Instance Method Summary

Entity - Inherited

#add_observer

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

The attribute_dictionaries method is used to retrieve the AttributeDictionaries collection attached to the entity.
#attribute_dictionary

The attribute_dictionary method is used to retrieve an attribute dictionary with a given name that is attached to an Entity.
#delete_attribute

The #delete_attribute method is used to delete an attribute from an entity.
#entityID

The entityID method is used to retrieve a unique ID assigned to an entity.
#get_attribute

The #get_attribute method is used to retrieve the value of an attribute in the entity’s attribute dictionary.
#inspect

The #inspect method is used to retrieve the string representation of the entity.
#model

The model method is used to retrieve the model for the entity.
#parent

The parent method is used to retrieve the parent of the entity.
#persistent_id

The #persistent_id method is used to retrieve a unique persistent id assigned to an entity.
#remove_observer

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

The set attribute is used to set the value of an attribute in an attribute dictionary with the given name.
#to_s

The #to_s method is used to retrieve the string representation of the entity.
#typename

The typename method retrieves the type of the entity, which will be a string such as “Face”, “Edge”, or “Group”.

Instance Attribute Details

#alpha ⇒ Float (rw)

The #alpha method is used to get the opacity of the material.

The value will be between 0.0 and 1.0. A value of 0.0 means that the material is completely transparent. A value of 1.0 means that the material is completely opaque.

Examples:

material = Sketchup.active_model.materials.add('Example')
material.alpha
# > 1.0

Returns:

  • (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 6.0

#alpha=(alpha) ⇒ Float (rw)

The #alpha= method is used to set the opacity of the material.

The value must be between 0.0 and 1.0. A value of 0.0 means that the material is completely transparent. A value of 1.0 means that the material is completely opaque.

Examples:

material =  Sketchup.active_model.materials.add('Example')
material.alpha = 0.5

Parameters:

  • alpha (Float) —

    An alpha value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 6.0

#ao_enabled=(enabled) (rw)

Examples:

material = Sketchup.active_model.materials.add("Material")
material.ao_enabled = true

Raises:

  • (ArgumentError) —

    if the ambient occlusion texture is not set before enabling ambient occlusion.

See Also:

Version:

  • SketchUp 2025.0.2

#ao_enabled? ⇒ Boolean (rw)

Note:

There is no setter for this property. Instead it’s dictated whether a #ao_texture is set.

Examples:

material = Sketchup.active_model.materials.add("Material")
material.ao_enabled?
# > false

See Also:

Version:

  • SketchUp 2025.0

#ao_strength ⇒ Float (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.ao_texture = 'path/to/ao_texture.png'
material.ao_strength
# > 1.0

Returns:

  • (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 2025.0

#ao_strength=(strenght) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.ao_texture = 'path/to/ao_texture.png'
material.ao_strength = 1.0

Parameters:

  • strenght (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 2025.0

#ao_texture ⇒ Sketchup::Texture (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.ao_texture = 'path/to/ao_texture.png'
material.ao_texture
# > nil

See Also:

Version:

  • SketchUp 2025.0

#ao_texture=(image_path) (rw) #ao_texture=(image_rep) #ao_texture=(texture)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.texture = 'path/to/texture.png'
material.ao_texture = 'path/to/ao_texture.png'

Overloads:

  • #ao_texture=(image_path)

    Parameters:

  • #ao_texture=(image_rep)

    Parameters:

  • #ao_texture=(texture)

    Copies another texture to this texture.

    Parameters:

Raises:

  • (ArgumentError) —

    if the image data of the texture is invalid or corrupt.

See Also:

Version:

  • SketchUp 2025.0

#color ⇒ Sketchup::Color (rw)

Note:

The alpha value of the Color object is not used for the material’s transparency. This is controlled by the #alpha property in order for textured materials to also have transparency.

The #color method is used to retrieve the color of the material.

If it uses a colorized Texture, this will return the average color of the texture.

Examples:

materials = Sketchup.active_model.materials.add('Example')
material.color = 'red'
color = material.color

See Also:

Version:

  • SketchUp 6.0

#color=(color) (rw)

Note:

The alpha value of the Color object is not used for the material’s transparency. This is controlled by the #alpha property in order for textured materials to also have transparency.

The #color= method is used to set the color of the material.

If the material has a Texture, then this turns it into a colorized texture.

To reset the color of a material with a colorized texture, set the color to nil. If the texture is not colorized it’ll be reset to some undefined default color.

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')
material.color = 'red'

Parameters:

See Also:

Version:

  • SketchUp 6.0

#colorize_type ⇒ Integer (rw)

Note:

This value is only relevant when the #materialType is set to MATERIAL_COLORIZED_TEXTURED.

The #colorize_type method retrieves the type of colorization of the material.

Material Colorize Types:

Examples:

material = Sketchup.active_model.materials.add('Example')
type = material.colorize_type

Returns:

  • (Integer) —

    One of Sketchup::Material::COLORIZE_* values.

Version:

  • SketchUp 2015

#colorize_type=(type) (rw)

Note:

This value is only relevant when the #materialType is set to MATERIAL_COLORIZED_TEXTURED.

The #colorize_type= method set the type of colorization of the material.

Material Colorize Types:

Examples:

material = Sketchup.active_model.materials.add('Example')
material.colorize_type = Sketchup::Material::COLORIZE_TINT

Parameters:

  • type (Integer) —

    One of Sketchup::Material::COLORIZE_* values.

Version:

  • SketchUp 2015

#metallic_factor ⇒ Float (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.metalness_enabled = true
material.metallic_factor
# > 1.0

Returns:

  • (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 2025.0

#metallic_factor=(factor) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.metalness_enabled = true
material.metallic_factor = 1.0

Parameters:

  • factor (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 2025.0

#metallic_texture ⇒ Sketchup::Texture (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.metalness_enabled = true
material.metallic_texture
# > nil

See Also:

Version:

  • SketchUp 2025.0

#metallic_texture=(image_path) (rw) #metallic_texture=(image_rep) #metallic_texture=(texture)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.texture = 'path/to/texture.png'
material.metallic_texture = 'path/to/metallic_texture.png'

Overloads:

  • #metallic_texture=(image_path)

    Parameters:

  • #metallic_texture=(image_rep)

    Parameters:

  • #metallic_texture=(texture)

    Copies another texture to this texture.

    Parameters:

Raises:

  • (ArgumentError) —

    if the image data of the texture is invalid or corrupt.

See Also:

Version:

  • SketchUp 2025.0

#metalness_enabled=(enabled) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.metalness_enabled = true

Parameters:

  • enabled (Boolean)

See Also:

Version:

  • SketchUp 2025.0

#metalness_enabled? ⇒ Boolean (rw)

Examples:

material = Sketchup.active_model.materials.add("Material")
material.metalness_enabled?
# > false

See Also:

Version:

  • SketchUp 2025.0

#name ⇒ String (rw)

The #name method retrieves the name of the material. This is the unique internal name of the object which should be used for retrieving the material from the model’s material list.

Use #display_name to display the name in the ::UI.

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('[Joe]')
# Use .name for the internal name of a material
puts material.name # Outputs "[Joe]"
# Use .display_name for presenting the material name
# to the UI like SketchUp does.
puts material.display_name # Outputs "Joe"

See Also:

Version:

  • SketchUp 6.0

#name=(str) ⇒ String (rw)

Note:

Since SketchUp 2018 this method will raise an ArgumentError if the name is not unique.

The #name= method sets the name of the material.

Examples:

Safely change name without raising errors

materials = Sketchup.active_model.materials
material = materials.add("Joe")
material.name = materials.unique_name('Jeff')

Parameters:

  • str (String) —

    the new material name

Raises:

  • (ArgumentError) —

    if the name is not unique to the model. (Added in SU2018)

Version:

  • SketchUp 8.0 M1

#normal_enabled=(enabled) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.normal_enabled = true

Parameters:

  • enabled (Boolean)

Raises:

  • (ArgumentError) —

    if the normal texture is not set before enabling normal mapping.

See Also:

Version:

  • SketchUp 2025.0.2

#normal_enabled? ⇒ Boolean (rw)

Examples:

material = Sketchup.active_model.materials.add("Material")
material.normal_enabled?
# > false

See Also:

Version:

  • SketchUp 2025.0

#normal_scale ⇒ Float (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.normal_texture = 'path/to/normal_texture.png'
material.normal_scale
# > 1.0

Returns:

  • (Float) —

    A value larger than or equal to 0.0.

See Also:

Version:

  • SketchUp 2025.0

#normal_scale=(scale) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.normal_texture = 'path/to/normal_texture.png'
material.normal_scale = 1.0

Parameters:

  • scale (Float) —

    A value larger than or equal to 0.0.

See Also:

Version:

  • SketchUp 2025.0

#normal_style ⇒ Integer (rw)

Material Normal Styles:

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.normal_texture = 'path/to/normal_texture.png'
material.normal_style
# > Sketchup::Material::NORMAL_STYLE_OPENGL

Returns:

  • (Integer) —

    One of Sketchup::Material::NORMAL_STYLE_* values.

See Also:

Version:

  • SketchUp 2025.0

#normal_style=(style) (rw)

Material Normal Styles:

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.normal_texture = 'path/to/normal_texture.png'
material.normal_style = Sketchup::Material::NORMAL_STYLE_DIRECTX

Parameters:

  • style (Integer)

See Also:

Version:

  • SketchUp 2025.0

#normal_texture ⇒ Sketchup::Texture (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.normal_texture = 'path/to/normal_texture.png'
material.normal_texture
# > #<Sketchup::Texture>

See Also:

Version:

  • SketchUp 2025.0

#normal_texture=(image_path) (rw) #normal_texture=(image_rep) #normal_texture=(texture)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.texture = 'path/to/texture.png'
material.normal_texture = 'path/to/normal_texture.png'

Overloads:

  • #normal_texture=(image_path)

    Parameters:

  • #normal_texture=(image_rep)

    Parameters:

  • #normal_texture=(texture)

    Copies another texture to this texture.

    Parameters:

Raises:

  • (ArgumentError) —

    if the image data of the texture is invalid or corrupt.

  • (ArgumentError) —

    if the image data is not 24 bits per pixels or higher.

See Also:

Version:

  • SketchUp 2025.0

#roughness_enabled=(enabled) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.roughness_enabled = true

Parameters:

  • enabled (Boolean)

See Also:

Version:

  • SketchUp 2025.0

#roughness_enabled? ⇒ Boolean (rw)

Examples:

material = Sketchup.active_model.materials.add("Material")
material.roughness_enabled?
# > false

See Also:

Version:

  • SketchUp 2025.0

#roughness_factor ⇒ Float (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.roughness_enabled = true
material.roughness_factor
# > 1.0

Returns:

  • (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 2025.0

#roughness_factor=(factor) (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.roughness_enabled = true
material.roughness_factor = 1.0

Parameters:

  • factor (Float) —

    A value between 0.0 and 1.0.

See Also:

Version:

  • SketchUp 2025.0

#roughness_texture ⇒ Sketchup::Texture (rw)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.roughness_enabled = true
material.roughness_texture
# > nil

See Also:

Version:

  • SketchUp 2025.0

#roughness_texture=(image_path) (rw) #roughness_texture=(image_rep) #roughness_texture=(texture)

Examples:

material = Sketchup.active_model.materials.add("PBR Material")
material.texture = 'path/to/texture.png'
material.roughness_texture = 'path/to/roughness_texture.png'

Overloads:

  • #roughness_texture=(image_path)

    Parameters:

  • #roughness_texture=(image_rep)

    Parameters:

  • #roughness_texture=(texture)

    Copies another texture to this texture.

    Parameters:

Raises:

  • (ArgumentError) —

    if the image data of the texture is invalid or corrupt.

See Also:

Version:

  • SketchUp 2025.0

#texture ⇒ Sketchup::Texture? (rw)

The #texture method retrieves the texture of the material.

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')
material.texture = 'path/to/metallic_texture.png'
texture = material.texture

Version:

  • SketchUp 6.0

#texture=(filename) (rw) #texture=(properties) #texture=(properties) #texture=(image_rep)

The #texture= method sets the texture for the material.

Setting the texture to nil will turn remove it and the material will use #color.

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')
material.texture = 'path/to/metallic_texture.png'

Overloads:

  • #texture=(filename)

    Parameters:

    • filename (String) —

      The file path to the texture the material should use.

  • #texture=(properties)

    Parameters:

  • #texture=(properties)

    Parameters:

  • #texture=(image_rep)

    Parameters:

    Version:

    • SketchUp 2018

Version:

  • SketchUp 6.0

#use_alpha? ⇒ Boolean (readonly)

Note:

that this is not affected by the alpha value of the #color object. Only the #alpha value will make this method return true.

The #use_alpha? method tells if the material uses transparency. It uses some tolerance checking to account for floating point precision noise.

Examples:

material = Sketchup.active_model.materials.add('Example')
material.use_alpha?
# > false

material.alpha = 0.5
material.use_alpha?
# > true

See Also:

Version:

  • SketchUp 6.0

Instance Method Details

#<=>(material) ⇒ Integer

The #<=> method is used to compare two materials based on ##display_name.

Examples:

materials =  Sketchup.active_model.materials
m1 = materials.add('Joe')
m2 = materials.add('Fred')
m1 <=> m2
# > 1

Parameters:

  • material (Material)

Returns:

  • (Integer) —

    0 if they are equal, 1 if material1 > material2, -1 if material1 < material2

Version:

  • SketchUp 6.0

#==(material) ⇒ Boolean

The #== method is used to test if two materials are the same.

Examples:

model = Sketchup.active_model
materials = model.materials
m1 = materials.add('Joe')
m2 = materials.add('Fred')
m1 == m2
# > false

Parameters:

  • material (Material)

Version:

  • SketchUp 6.0

#colorize_deltas ⇒ Array(Float, Float, Float)

The #colorize_deltas method retrieves the HLS delta for colorized materials.

Examples:

material = Sketchup.active_model.materials.add('Example')
h, l, s = material.colorize_deltas

Returns:

  • (Array(Float, Float, Float)) —

    An array of floats representing the HLS delta.

Version:

  • SketchUp 2015

#display_name ⇒ String

The #display_name method retrieves the name that is displayed within SketchUp for the material.

This should be used when presenting the name in the ::UI, but the returned name cannot be used as a key in Model#materials.

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('[Joe]')
# Use .name for the internal name of a material
puts material.name # Outputs "[Joe]"
# Use .display_name for presenting the material name
# to the UI like SketchUp does.
puts material.display_name # Outputs "Joe"

See Also:

Version:

  • SketchUp 6.0

#materialType ⇒ Integer

The #materialType method retrieves the type of the material.

Material Types:

The constants were added in SketchUp 2015.

Examples:

material = Sketchup.active_model.materials.add('Example')
material.materialType == Sketchup::Material::MATERIAL_SOLID
# > true

Returns:

  • (Integer) —

    One of Sketchup::Material::MATERIAL_* values.

Version:

  • SketchUp 6.0

#owner_type ⇒ Integer

The #owner_type method is used to determine what owns the material.

Material Owner Types:

Version:

  • SketchUp 2019.2

#save_as(filename) ⇒ Boolean

Note:

You must remember to append “.skm” to the filename as this will not be done automatically.

The #save_as method is used to write a material to a SKM file.

Examples:

filename = File.join(Sketchup.temp_dir, 'su_test.skm')
materials = Sketchup.active_model.materials
material = materials.add("Hello World")
material.color = 'red'
material.save_as(filename)

Parameters:

  • filename (String) —

    the path to the SKM file to load.

Version:

  • SketchUp 2017

#workflow ⇒ Integer

Material Workflows:

When the workflow returns WORKFLOW_PBR_METALLIC_ROUGHNESS the properties listed under PBR Metallic Roughness Workflow are relevant.

Examples:

Classic material

material = Sketchup.active_model.materials.add("Material")
workflow = material.workflow
# > workflow == Sketchup::Material::WORKFLOW_CLASSIC

PBR material

material = Sketchup.active_model.materials.add("PBR Material")
material.metalness_enabled = true # Or any of the other PBR properties.
workflow = material.workflow
# > workflow == Sketchup::Material::WORKFLOW_PBR_METALLIC_ROUGHNESS

Returns:

  • (Integer) —

    One of Sketchup::Material::WORKFLOW_* values.

Version:

  • SketchUp 2025.0

#write_thumbnail(path, max_size) ⇒ Boolean?

The #write_thumbnail method writes a bitmap thumbnail to the given file name.

Examples:

model = Sketchup.active_model
model.materials.each { |material|
  thumbnail_file = File.join(Sketchup.temp_dir, "#{material.display_name}.png")
  material.write_thumbnail(thumbnail_file, 128)
}

Parameters:

  • path (String) —

    The file path for the thumbnail.

  • max_size (Integer) —

    The maximum width or height of the generated image.

Returns:

  • (Boolean, nil) —

    true if successful, false if unsuccessful. nil if arguments are invalid.

Version:

  • SketchUp 8.0 M1