Class: Sketchup::Material

Inherits:
Entity
  • Object
show all
Includes:
Comparable

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

Workflow Constant Summary # collapse

Sketchup::Material::WORKFLOW_CLASSIC
Sketchup::Material::WORKFLOW_PBR_METALLIC_ROUGHNESS

Normal Style Summary # collapse

Sketchup::Material::NORMAL_STYLE_OPENGL
Sketchup::Material::NORMAL_STYLE_DIRECTX

Material Type Constant Summary # collapse

Sketchup::Material::MATERIAL_SOLID
Sketchup::Material::MATERIAL_TEXTURED
Sketchup::Material::MATERIAL_COLORIZED_TEXTURED

Colorize Type Constant Summary # collapse

Sketchup::Material::COLORIZE_SHIFT
Sketchup::Material::COLORIZE_TINT

Owner Type Constant Summary # collapse

Sketchup::Material::OWNER_MANAGER
Sketchup::Material::OWNER_IMAGE
Sketchup::Material::OWNER_LAYER

PBR Metallic Roughness Workflow # collapse

Instance Method Summary # collapse

Methods inherited from Entity

#add_observer, #attribute_dictionaries, #attribute_dictionary, #delete_attribute, #deleted?, #entityID, #get_attribute, #inspect, #model, #parent, #persistent_id, #remove_observer, #set_attribute, #to_s, #typename, #valid?

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:

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:

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0

↑ #alpha ⇒ Float

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

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.

Returns:

  • (Float)

See Also:

Version:

  • SketchUp 6.0

↑ #ao_enabled? ⇒ Boolean PBR Metallic Roughness Workflow

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

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 2025.0

↑ #ao_strength ⇒ Float PBR Metallic Roughness Workflow

Returns A value between 0.0 and 1.0.

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) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

Examples:

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

Returns:

See Also:

Version:

  • SketchUp 2025.0

↑ #ao_texture=(image_path) ⇒ Object #ao_texture=(image_rep) ⇒ Object #ao_texture=(texture) ⇒ Object PBR Metallic Roughness Workflow

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) ⇒ Object

    Parameters:

  • #ao_texture=(image_rep) ⇒ Object

    Parameters:

  • #ao_texture=(texture) ⇒ Object

    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

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

Returns:

See Also:

Version:

  • SketchUp 6.0

↑ #color=(color) ⇒ Object

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_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

↑ #colorize_type ⇒ Integer

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) ⇒ Object

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

↑ #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 Sketchup::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"

Returns:

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

↑ #metallic_factor ⇒ Float PBR Metallic Roughness Workflow

Returns A value between 0.0 and 1.0.

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) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

Examples:

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

Returns:

See Also:

Version:

  • SketchUp 2025.0

↑ #metallic_texture=(image_path) ⇒ Object #metallic_texture=(image_rep) ⇒ Object #metallic_texture=(texture) ⇒ Object PBR Metallic Roughness Workflow

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) ⇒ Object

    Parameters:

  • #metallic_texture=(image_rep) ⇒ Object

    Parameters:

  • #metallic_texture=(texture) ⇒ Object

    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) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

Examples:

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

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 2025.0

↑ #name ⇒ String

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"

Returns:

See Also:

Version:

  • SketchUp 6.0

↑ #name=(str) ⇒ String

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

Returns:

Raises:

  • (ArgumentError) —

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

Version:

  • SketchUp 8.0 M1

Known Bugs:

  • SketchUp 2018 would raise an error if you named material the name it already had.

↑ #normal_enabled? ⇒ Boolean PBR Metallic Roughness Workflow

Note:

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

Examples:

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

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 2025.0

↑ #normal_scale ⇒ Float PBR Metallic Roughness Workflow

Returns A value larger than or equal to 0.0.

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) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

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) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

Examples:

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

Returns:

See Also:

Version:

  • SketchUp 2025.0

↑ #normal_texture=(image_path) ⇒ Object #normal_texture=(image_rep) ⇒ Object #normal_texture=(texture) ⇒ Object PBR Metallic Roughness Workflow

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) ⇒ Object

    Parameters:

  • #normal_texture=(image_rep) ⇒ Object

    Parameters:

  • #normal_texture=(texture) ⇒ Object

    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

↑ #owner_type ⇒ Integer

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

Material Owner Types:

Returns:

  • (Integer)

Version:

  • SketchUp 2019.2

↑ #roughness_enabled=(enabled) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

Examples:

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

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 2025.0

↑ #roughness_factor ⇒ Float PBR Metallic Roughness Workflow

Returns A value between 0.0 and 1.0.

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) ⇒ Object PBR Metallic Roughness Workflow

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 PBR Metallic Roughness Workflow

Examples:

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

Returns:

See Also:

Version:

  • SketchUp 2025.0

↑ #roughness_texture=(image_path) ⇒ Object #roughness_texture=(image_rep) ⇒ Object #roughness_texture=(texture) ⇒ Object PBR Metallic Roughness Workflow

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) ⇒ Object

    Parameters:

  • #roughness_texture=(image_rep) ⇒ Object

    Parameters:

  • #roughness_texture=(texture) ⇒ Object

    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

↑ #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.

Returns:

  • (Boolean)

Version:

  • SketchUp 2017

↑ #texture ⇒ Sketchup::Texture?

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

Returns:

Version:

  • SketchUp 6.0

↑ #texture=(filename) ⇒ Object #texture=(properties) ⇒ Object #texture=(properties) ⇒ Object #texture=(image_rep) ⇒ Object

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) ⇒ Object

    Parameters:

    • filename (String) —

      The file path to the texture the material should use.

  • #texture=(properties) ⇒ Object

    Parameters:

  • #texture=(properties) ⇒ Object

    Parameters:

  • #texture=(image_rep) ⇒ Object

    Parameters:

    Version:

    • SketchUp 2018

Version:

  • SketchUp 6.0

↑ #use_alpha? ⇒ Boolean

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

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 6.0

↑ #workflow ⇒ Integer PBR Metallic Roughness Workflow

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