SketchUp MXS Export

The following discusses how MXS files are written and therefore pertains only to the Render Suite plugin.

When exporting MXS files, do not use File > Export > 3D Model. The ability to do this is added by the plugin's C++ exporter, but it is intended to be used not directly, but rather by the plugin itself, after data in the model has been synchronized. Instead, use the menu & toolbar functions specifically provided for exporting MXS files: Export MXS, Export to Studio, etc.

Instances 

By default, the plugin's Use Instances option is enabled. This is a good thing, since SketchUp is still a 32-bit application, and can therefore use a maximum of 2GB of memory. Instances can drastically reduce the amount of memory required to export a model; additionally, they also enable Maxwell Render to use less memory at render time, though this is not as important, since Maxwell is offered in a 64-bit version, which effectively has no memory limit.

There are some things which are worth mentioning about how instances in SketchUp relate to instances in Maxwell. Conceptually, an instance is a reference to some other entity. In SketchUp, this relationship is generic; that is, an instance (i.e. a Component Instance) may reference another instance. This is not the case in Maxwell; here, there is always a one-to-many relationship between geometry and instances, where any given instance references an actual mesh object, and cannot reference another instance.

As such, the plugin must analyze the SketchUp document structure at export time, and arrange for one, and only one, physical mesh to be created for each Component Definition which is used in the document. All Component Instances which reference each Definition must then be collected into a list, where each resulting Maxwell instance's transformation takes into account any nested transformations which may be effective for the SketchUp Component Instance in question (since SketchUp Component Instances may be included in the Definitions of other Component Instances).

The ultimate result of all of this is that it is not technically possible to represent the model in MXS format using the same conceptual structure as is present in the SketchUp document. Specifically, the tree-like logical structure which is created when SketchUp Components reference other SketchUp Components cannot be represented in the MXS, since Maxwell instances cannot refer to other Maxwell instances.

The structure which will be seen in the MXS, therefore, is slightly different than one might expect. The plugin organizes objects in the MXS by type: Component, Group, and Faces. In the MXS structure, these objects may end up having any number of Maxwell instances which refer to them. If a particular Component Definition is used in multiple other definitions in SketchUp, it will still appear only once in the MXS file -- the remaining references in SketchUp will appear in the MXS as Maxwell instances attached to whichever SketchUp entity had its definition exported first.

This maximizes the use of memory, since each physical definition will only ever exist as actual mesh geometry once in the MXS file.

Groups 

In SketchUp, Groups are really a special kind of Component Instance. As such, it is entirely possible for the plugin to export any recurring instances of a Group using the same instance mechanism as is described above with regards to Component Instances.

That is to say, only one copy of any particular Group in SketchUp will be exported as actual mesh geometry; any other occurrences can and will be exported as a Maxwell instance (assuming the plugin's Use Instances option is enabled).

Faces 

Faces in SketchUp may be owned by a Group, a Component Definition, or the Document itself. During export, the fate of any given face depends on which of these it belongs to. Faces contained in Groups and Components may be separated by material, face, or not at all.

Object Naming 

The MXS format requires that objects each be given unique names. As such, objects in the MXS are named for their corresponding SketchUp entity, along with a bracketed number:

<Component#1> [1.2.1.19]

The bracketed number encodes information about how the object was exported. The first number indicates how faces were separated, where:

NumberSeparation By
0None
1Face
2Material

<Component#1>, then, was exported with its Separate by Face flag enabled. The second number indicates if UV coordinates were overridden, where:

NumberUV Coordinates
0 Default SketchUp
1 Ignore Distortion
2 Cubic
3 Planar
4 Spherical
5 Camera

<Component#1> was exported, then, using Cubic UV coordinates. The third number deals with situations in which multiple copies of the same entity are exported, and indicates with which copy any given object corresponds; this, then, was the second copy of <Component#1> to be exported (numbering starts at 0).

The fourth number will only appear when the object is exported using Separate by Face or Separate by Material, and indicates to which face the mesh corresponds, inside the parent Component or Group.

Additionally, an instance's name will have a fifth number, indicating which of several copies it is.

Material Naming

Materials in an MXS are also required to have unique names. In an MXS, you may find more than one copy of the same SketchUp material, where the SketchUp material name has been changed, similar to this:

Material [5]

Material here corresponds to SketchUp's name for the material, and [5] to the index of the material's texture inside of the SketchUp TextureWriter, which is a SketchUp API tool used by plugin code to obtain unique textures for faces which require them.

When a face has a distorted texture, it is necessary to create both a unique texture, on disk, and a unique Maxwell material for use with that texture, in the exported MXS. This is because when a texture is distorted on a face, SketchUp uses a combination of modified UV coordinates and modified texture pixels to accomplish the effect.

Layer Usage

The SketchUp concept of layers cannot be represented in the MXS format. In SketchUp, an entity's Layer is unrelated to its position in the document hierarchy; rather, it is more like an attribute attached to an entity.

Therefore, the way in which the plugin uses SketchUp Layers for organization in the MXS differs conceptually from the way it is used in SketchUp. When entities are exported, the plugin will attempt to place them under a node in the MXS which is named for the SketchUp Layer that they use. For faces, this will generally work fine, but when dealing with instances, the situation becomes slightly more complicated.

As discussed above in the Instances topic, only one actual mesh will be exported for each Component Definition, regardless of how many references to this definition exist in the SketchUp document. This presents an issue with the organization of objects by layer name, because only an actual mesh may be categorized in the MXS structure; instances are always attached to the mesh they reference. That is to say, instances cannot be organized by layer name in the MXS. To demonstrate, consider the following SketchUp document:

If the plugin means to export the definition for Cube only once, and if all instances of the mesh for Cube must be attached to its mesh definition, then we can see that it will not be possible to respect the per-Layer organization being used in the SketchUp document. When exported to MXS, this document may therefore have a structure that looks more like this:

So, as can be seen, the 'layer' node (the one in the MXS which will be given a SketchUp Layer name) which appears in the MXS is the one for the Layer of the Cube instance which was encountered first during the export, and was therefore exported as a mesh object, rather than an instance. The other three instances of Cube appear in the MXS as instances attached to that mesh, and being instances, have no parent which can be used to indicate their SketchUp Layer.