Boxshot supports a single scene object per opened document. You can’t create or open other scene from the script, just work with the one that is currently loaded. Some examples of scene usage are given here and here. The more structured list of properties and methods is below.

Scene nodes

Each scene has one and only one root node. You can get its children nodes, but can’t edit it, as it is read-only. However, it is OK to add, clone or remove its children. Use the following code to get the root node:

var root = scene.root;

However, you’ll get error message if you try any of the following calls:

scene.root.name = "my name";
scene.root.visible = false;
scene.root.translation = vec3(1, 1, 1);

You can get the children nodes exactly as for any other node in the scene:

var children = scene.root.children;
print("the root node has %1 children", children.length);

Please see the following links to know about creating, traversing, editing and deleting scene nodes.

Saving And Exporting

Boxshot saves scenes to internal format, it also allows you to export to some well-known 3D formats, like Collada or 3D PDF. There is no big difference from the scripting point of view which format to use. All the saving is done this way:

scene.save(filename); // everything by-default version
scene.save(filename, params); // version with parameters

The params variable is a dictionary with some settings for saving plugin and Boxshot itself. Boxshot tries to guess the saving format using the file name extensio you provide. All the saving plugins report Boxshot the extensions they support, so it can find the appropriate plugin easily. If you need to save a file with non-standard extension, you may pass a mime-type as a parameter:

var params = {"mime": "model/dae"};
scene.save("collada-file.txt", params);

Some plugins support boolean parameter draft that controls the rendering quality.

To save the current scene as a Boxshot project, use this code:

scene.save("file.boxshot");

Modifying Scene Properties

You can access all the scene properties using scripts. Here’s how:

// set ambient to 50%
scene.ambientLevel = 0.5;

// turn skylight on and set it to 20%
scene.showSkylight = true;
scene.skylightLevel = 0.2;

// load background image and set magenta tint color
scene.backgroundColor = color("#FF00FF");
scene.backgroundImage = "filename.jpg";

// turn transparent background on
scene.transparentBackground = true;

// hide the floor
scene.showFloor = false;

// diffuse floor lighting
scene.diffuseFloorLighting = true;

// load the environment image
scene.environmentImage = "filename.hdr";
scene.environmentIntensity = 2;
scene.environmentOffsetH = 10;
scene.environmentOffsetV = -5;

// floor reflection
scene.floorReflectionEnabled = true;
scene.floorReflectionLevel = 0.2;
scene.floorReflectionBlur = 0.05;
scene.floorReflectionDecay = 0.5;

Rendering

See the dedicated rendering page for more details.