Home
Developer Docs

Material

SketchUp 6.0+

class

Parent: Entity

Introduction

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.)

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

Methods

Material.<=>SketchUp 6.0+

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

Arguments:

material1
A Material object.
material2
A Material object.

Returns:

status
0 if they are equal, positive number if material1 > material2, negative if material1 < material2
 model = Sketchup.active_model
 materials = model.materials
 m1 = materials.add('Joe')
 m2 = materials.add('Fred')
 p m1 <=> m2

Material.==SketchUp 6.0+

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

Arguments:

material1
A Material object.
material2
A Material object.

Returns:

status
true if the Materials are the same, false if they are different
 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

Material.alphaSketchUp 6.0+

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.

Returns:

alpha
a number between 0 and 1
 alpha_value = Sketchup.active_model.materials[0].alpha

Material.alpha=SketchUp 6.0+

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.

Arguments:

alpha
An opacity value.

Returns:

status
the newly set opacity value
 model = Sketchup.active_model
 materials = model.materials
 material = materials.add('Joe')
 material.alpha = 0.5

Material.colorSketchUp 6.0+

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

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

Returns:

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

Material.color=SketchUp 6.0+

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.

Arguments:

color
A Color object.

Returns:

color
the newly set Color object's name
 model = Sketchup.active_model
 materials = model.materials
 material = materials.add('Joe')
 material.color = 'red'

Material.colorize_deltasSketchUp 2015+

The colorize_deltas method retrieves the HLS delta for colorized materials.

Returns:

Array
An array of floats representing the HLS delta.
 material = Sketchup.active_model.materials[0]
 h, l, s = material.colorize_deltas

Material.colorize_typeSketchUp 2015+

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),
  • Returns:

    type
    the colorize type for the Material object.
     material = Sketchup.active_model.materials[0]
     type = material.colorize_type

Material.colorize_type=SketchUp 2015+

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),
  • Arguments:

    material1
    type - the new colorize type for the Material object.

    Returns:

    type
    the colorize type for the Material object.
     material = Sketchup.active_model.materials[0]
     material.colorize_type = Sketchup::Material::COLORIZE_TINT

Material.display_nameSketchUp 6.0+

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.

Returns:

name
the display name for the material
 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"

Material.materialTypeSketchUp 6.0+

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.

Returns:

type
the material type for the Material object. See summary for details.
 material = Sketchup.active_model.materials[0]
 type = material.materialType

Material.nameSketchUp 6.0+

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.

Returns:

name
the name of the Material object
 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"

Material.name=SketchUp 8.0 M1+

Sets the name of the material.

Returns:

name
the newly set material name.
 materials = Sketchup.active_model.materials
 material = materials.add("Joe")
 material.name = 'Jeff'

Material.textureSketchUp 6.0+

The texture method retrieves the texture of the material.

Returns:

texture
the Texture object within the Material. Returns nil if the Material does not have a Texture.
 model = Sketchup.active_model
 materials = model.materials
 material = materials.add('Joe')
 material.texture = "C:/Materials/Carpet.jpg"
 texture = material.texture

Material.texture=SketchUp 6.0+

The texture= method sets the texture for the material.

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

Arguments:

texture
The Texture object to apply to the material.

Returns:

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

Material.use_alpha?SketchUp 6.0+

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.

Returns:

type
the material type for the Material object. See summary for details.
 material = Sketchup.active_model.materials[0]
 is_alpha = material.use_alpha?

Material.write_thumbnailSketchUp 8.0 M1+

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

Arguments:

filename
The file name for the thumbnail.
resolution
The resolution of the thumbnail.

Returns:

status
true if successful, false if unsuccessful.
 model = Sketchup.active_model
 model.materials.each { |material|
   thumbnail_file = "C:/tmp/materials/#{material.display_name}.png"
   material.write_thumbnail(thumbnail_file, 128)
 }

  

Trimble Home
About Trimble - Privacy Policy - Contact Us