Boxshot has quite complex materials, so it would be better to read about them first.

Obtaining materials

Materials can be obtained from the shape objects only. Let’s create a cylinder and get its materials:

var m = scene.root.addMesh("cylinder", "generator.simple.cylinder");
var mtls = m.materials;
print("Cylinder has %1 materials", mtls.length);
for (var i = 0; i < mtls.length; i++)
    print("%1. %2", i + 1, mtls[i].name);

If you know the name, there’s an easier way to get a material:

var m = scene.root.addMesh("sphere", "generator.simple.sphere");
var mtl = m.material("Surface");

Basic properties

Here’s how to modify the most common properties of the material:

// create a sphere and get its material
var m = scene.root.addMesh("sphere", "generator.simple.sphere");
var mtl = m.material("Surface");

// diffuse parameters
mtl.diffuseTint = color(1, 0.5, 0, 1);
mtl.diffuseTexture = "filename.jpg";
mtl.crop = [0, 0.5, 1, 0.5]; // left, top, width, height. all in 0..1 range
mtl.textureTransformation = 0; // 0..5, see below

// specular parameters
mtl.specularLevel = 0.5;
mtl.glossiness = 0.2;
mtl.specularColor = color("#FF00FF");

// bump
mtl.bumpLevel = 0.75;
mtl.bumpTexture = "heightmap.png";

// reflection
mtl.reflectionLevel = 0.3;
mtl.fresnelReflection = true;
mtl.physicalReflection = true; // raytraced reflection
mtl.reflectionTexture = "chrome.png";

// refraction
mtl.refractionIndex = 2.2;
mtl.opacity = 0.9;

The properties above are grouped the same way as in the materials panel in the user interface.

Texture transformation property is an integer in range 0 to 5 with the following meaning of numbers:

  • 0 - no transformation
  • 1 - rotate 90 cw
  • 2 - rotate 90 ccw
  • 3 - rotate 180
  • 4 - flip horizontally
  • 5 - flip vertically

Advanced properties

Here is the script that adjusts the advanced material’s parameters in the same order as they are listed in the materials panel.

// create a sphere and get its material
var m = scene.root.addMesh("sphere", "generator.simple.sphere");
var mtl = m.material("Surface");

// advanced reflection parameters
mtl.reflectionTint = color(0, 1, 0, 1);
mtl.reflectionMask = "mask.png";
mtl.reflectionBlur = 0.2;
mtl.reflectionSamples = 4;
mtl.reflectionDepth = 16;
mtl.reflectionExitColor = color(1, 0, 1, 1);

// advanced refraction parameters
mtl.refractionTint = color(1, 1, 0, 1);
mtl.refractionBlur = 0.1;
mtl.refractionSamples = 4;
mtl.refractionDepth = 3;
mtl.refractionExitColorEnabled = true;
mtl.refractionExitColor = color(0, 0, 0);

// refraction fog
mtl.refractionFogLevel = 0.2;
mtl.refractionFogColor = color(0, 1, 0, 1);

// other properties
mtl.diffuseLighting = true;
mtl.wrapUV = true;

Cloning materials

Each material can return a dictionary of its parameters.

var s = scene.root.addMesh("sphere", "generator.simple.sphere");
var m = s.material("Surface");
var p = m.parameters;
for (var k in p) 
    print("%1 -> %2", k, p[k]);

You may build your own dictionary and pass it to the material. Just use the identifiers from the real parameters' dictionary:

var d = {"opacity": 0.5, "diffuse-tint": "#FF8000"};
m.parameters = d;

Boxshot silently skips the unknown items, so if you don’t see the change you need after applying the parameters, please check the syntax if the dictionary keys.

Now you can copy one material to another, exactly as you do by dragging it to another mesh. Here’s the code:

var s1 = scene.root.addMesh("sphere 1", "generator.simple.sphere");
var m1 = s1.material("Surface");
m1.diffuseColor = color(1, 0, 0);
m1.opacity = 0.8;

var s2 = scene.root.addMesh("sphere 2", "generator.simple.sphere");
s2.translation = vec3(0, 0, 20);
var m2 = s2.material("Surface");
m2.parameters = m1.parameters;

The very last line copies all the material’s parameters from the first sphere to the second one.