Class: Sketchup::Material

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

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 materials, color, and classes that can be converted to a color.

The following are valid (assuming the existence of a Material mat1.)

Examples:

face.material = mat1
face.material = "red"
face.material = 0xff0000

Version:

SketchUp 6.0

Constant Summary

COLORIZE_SHIFT =

Constants

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 27
```
nil
```
COLORIZE_TINT =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 28
```
nil
```
MATERIAL_COLORIZED_TEXTURED =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 30
```
nil
```
MATERIAL_SOLID =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 31
```
nil
```
MATERIAL_TEXTURED =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 32
```
nil
```
OWNER_IMAGE =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 34
```
nil
```
OWNER_LAYER =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 35
```
nil
```
OWNER_MANAGER =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/Sketchup/Material.rb', line 36
```
nil
```

Instance Attribute Summary

#alpha ⇒ Float rw

The alpha method is used to get the opacity of the material.
#alpha=(alpha) ⇒ Float rw

The alpha= method is used to set the opacity of the material.
#color ⇒ Sketchup::Color rw

The color method is used to retrieve the color of the material.
#color=(color) ⇒ Sketchup::Color, ... rw

The color= method is used to set the color of the material.
#colorize_type ⇒ Integer rw

The colorize_type method retrieves the type of colorization of the material.
#colorize_type=(type) ⇒ Integer rw

The colorize_type method set the type of colorization of the material.
#name ⇒ String rw

The name method retrieves the name of the material.
#name=(str) ⇒ String rw

The #name= method sets the name of the material.
#texture ⇒ Sketchup::Texture^? rw

The texture method retrieves the texture of the material.
#texture=(filename) rw

The texture= method sets the texture for the material.
#use_alpha? ⇒ Boolean readonly

The use_alpha? method tells if the material uses transparency.

`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

#<=>(material2) ⇒ Integer

The <=> method is used to compare two materials based on name.
#==(material2) ⇒ Boolean

The == method is used to test if two materials are the same.
#colorize_deltas ⇒ Array(Float, Float, Float)

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

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

The materialType method retrieves the type of the material.
#owner_type ⇒ Integer

The #owner_type method is used to determine if the material is owned by a Materials.
#save_as(filename) ⇒ Boolean

The #save_as method is used to write a material to a SKM file.
#write_thumbnail(path, resolution) ⇒ Boolean

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

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

alpha_value = Sketchup.active_model.materials[0].alpha

Returns:

(Float) —

a number between 0 and 1

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:

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

Parameters:

alpha (Float) —

An opacity value.

Returns:

(Float) —

the newly set opacity value

Version:

SketchUp 6.0

#color ⇒ Sketchup::Color (rw)

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

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

Examples:

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

Returns:

(Sketchup::Color) —

a Color object

Version:

SketchUp 6.0

#color=(color) ⇒ Sketchup::Color, ... (rw)

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 texture, set the color to nil.

Examples:

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

Parameters:

color (Sketchup::Color, String, nil) —

A Color object.

Returns:

(Sketchup::Color, String, nil) —

the newly set Color object

Version:

SketchUp 6.0

#colorize_type ⇒ `Integer` (rw)

The colorize_type method retrieves the type of colorization of the material. This value is only relevant when the materialType is set to 2 (colorized textured). Types include:

- 0 = shift (Sketchup::Material::COLORIZE_SHIFT),
- 1 = tint (Sketchup::Material::COLORIZE_TINT),

Examples:

material = Sketchup.active_model.materials[0]
type = material.colorize_type

Returns:

(Integer) —

the colorize type for the Material object.

Version:

SketchUp 2015

#colorize_type=(type) ⇒ `Integer` (rw)

The colorize_type method set the type of colorization of the material. This value is only relevant when the materialType is set to 2 (colorized textured). Types include:

- 0 = shift (Sketchup::Material::COLORIZE_SHIFT),
- 1 = tint (Sketchup::Material::COLORIZE_TINT),

Examples:

material = Sketchup.active_model.materials[0]
material.colorize_type = Sketchup::Material::COLORIZE_TINT

Parameters:

type (Integer) —

the new colorize type for the Material object.

Returns:

(Integer) —

the colorize type for the Material object.

Version:

SketchUp 2015

#name ⇒ String (rw)

The name method retrieves the name of the material. This is the 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:

(String) —

the name of the Material object

Version:

SketchUp 6.0

#name=(str) ⇒ String (rw)

Note:

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

Note:

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

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:

(String) —

the newly set material name.

Raises:

(ArgumentError) —

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

Version:

SketchUp 8.0 M1

#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 = "C:/Materials/Carpet.jpg"
texture = material.texture

Returns:

(Sketchup::Texture, nil) —

the Texture object within the Material. Returns nil if the Material does not have a texture.

Version:

SketchUp 6.0

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

The texture= method sets the texture for the material.

Setting the texture to nil will turn it into a solid color

Examples:

model = Sketchup.active_model
materials = model.materials
material = materials.add('Joe')
material.texture = "C:/Materials/Carpet.jpg"

Overloads:

#texture=(filename)
Parameters:
- filename (String) —
  
  The file path to the texture the material should use.
#texture=(properties)
Parameters:
- properties (Array(String, Length, Length)) —
  
  An array with the texture file path and optionally the width and height.
#texture=(image_rep)
Parameters:
- image_rep (Sketchup::ImageRep) —
  
  The pixel data representing the texture. (Added in SketchUp 2018)

Version:

SketchUp 6.0

#use_alpha? ⇒ `Boolean` (readonly)

The use_alpha? method tells if the material uses transparency.

Note that this is not affected by the alpha value of the color object. Only the .alpha value and transparent texture will make this method return true.

Examples:

material = Sketchup.active_model.materials[0]
is_alpha = material.use_alpha?

Version:

SketchUp 6.0

Instance Method Details

#<=>(material2) ⇒ `Integer`

The <=> method is used to compare two materials based on name. The number returned relates to the “string distance” between the names.

Examples:

model = Sketchup.active_model
materials = model.materials
m1 = materials.add('Joe')
m2 = materials.add('Fred')
p m1 <=> m2

Parameters:

material2 (Material) —

A Material object.

Returns:

(Integer) —

0 if they are equal, positive number if material1 > material2, negative if material1 < material2

Version:

SketchUp 6.0

#==(material2) ⇒ `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')
if (m1 == m2)
  UI.messagebox('The Materials are equal.')
else
  UI.messagebox('The Materials are not equal.')
end

Parameters:

material2 (Material) —

A Material object.

Returns:

(Boolean) —

true if the materials are the same, false if they are different

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[0]
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"

Returns:

(String) —

the display name for the material

Version:

SketchUp 6.0

#materialType ⇒ `Integer`

The materialType method retrieves the type of the material. Types include:

- 0 = solid (Sketchup::Material::MATERIAL_SOLID),
- 1 = textured (Sketchup::Material::MATERIAL_TEXTURED),
- 2 = colorized textured (Sketchup::Material::MATERIAL_COLORIZED_TEXTURED).

The constants where added in SketchUp 2015.

Examples:

material = Sketchup.active_model.materials[0]
type = material.materialType

Returns:

(Integer) —

the material type for the Material object. See summary for details.

Version:

SketchUp 6.0

#owner_type ⇒ `Integer`

The #owner_type method is used to determine if the material is owned by a Materials.

Returned value is one of:

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

Version:

SketchUp 2019.2

#save_as(filename) ⇒ `Boolean`

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

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

Examples:

filename = File.join(ENV['HOME'], 'Desktop', '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) —

‘true` if successful

Version:

SketchUp 2017

#write_thumbnail(path, resolution) ⇒ `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 = "C:/tmp/materials/#{material.display_name}.png"
  material.write_thumbnail(thumbnail_file, 128)
}

Parameters:

path (String) —

The file path for the thumbnail.
resolution (Integer) —

The resolution of the thumbnail.

Returns:

(Boolean) —

true if successful, false if unsuccessful.

Version:

SketchUp 8.0 M1

Class: Sketchup::Material

Overview

Constant Summary

Instance Attribute Summary

Entity - Inherited

Instance Method Summary

Entity - Inherited

Instance Attribute Details

#alpha ⇒ Float (rw)

#alpha=(alpha) ⇒ Float (rw)

#color ⇒ Sketchup::Color (rw)

#color=(color) ⇒ Sketchup::Color, ... (rw)

#colorize_type ⇒ Integer (rw)

#colorize_type=(type) ⇒ Integer (rw)

#name ⇒ String (rw)

#name=(str) ⇒ String (rw)

#texture ⇒ Sketchup::Texture? (rw)

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

#use_alpha? ⇒ Boolean (readonly)

Instance Method Details

#<=>(material2) ⇒ Integer

#==(material2) ⇒ Boolean

#colorize_deltas ⇒ Array(Float, Float, Float)

#display_name ⇒ String

#materialType ⇒ Integer

#owner_type ⇒ Integer

#save_as(filename) ⇒ Boolean

#write_thumbnail(path, resolution) ⇒ Boolean

`Entity` - Inherited

`Entity` - Inherited

#alpha ⇒ `Float` (rw)

#alpha=(alpha) ⇒ `Float` (rw)

#colorize_type ⇒ `Integer` (rw)

#colorize_type=(type) ⇒ `Integer` (rw)

#texture ⇒ Sketchup::Texture^? (rw)

#use_alpha? ⇒ `Boolean` (readonly)

#<=>(material2) ⇒ `Integer`

#==(material2) ⇒ `Boolean`

#colorize_deltas ⇒ Array(`Float`, `Float`, `Float`)

#materialType ⇒ `Integer`

#owner_type ⇒ `Integer`

#save_as(filename) ⇒ `Boolean`

#write_thumbnail(path, resolution) ⇒ `Boolean`