7. Import and Export

This section contains the documentation of all import and export modules of Ayam.

7.1 Import and Export Plugin Management

Except for RIB export, all import/export modules of Ayam are plugins that need to be loaded into the application before possible usage. Loading of an import/export plugin may be done in three different ways:

1. explicitly via the main menu entry "File/Load Plugin",
2. automatically on application startup via a script (by adding e.g. "plugins/loaddxfio.tcl" to the "Scripts" preference setting),
3. implicitly via normal scene IO.

   Implicit loading means one can simply use the main menu entries "File/Open" and "File/Save as" (or the corresponding keyboard shortcuts) and specify a filename with the appropriate extension (e.g. ".dxf").^[∗] Ayam will then load the matching plugin ("dxfio") and will also open the import (or export) options dialog with the "FileName" option already set to the filename chosen before. Of course, implicit plugin loading requires that the "Plugins" preferences are correctly set.

7.2 Import and Export Plugin Overview

The following table lists the Ayam features supported by the various import plugins.

Not all features of Ayam are supported in the various export options. The following table gives an overview of the supported features per export file format.

^a : will be converted to NURBS
^b : will be converted to PolyMeshes
^c : 3D trim curves exported as PolyLines
^d : some quadrics are converted to NURBS (refer to plugin documentation)
^e : some parametrics are converted to NURBS (refer to plugin documentation)

Note that a successful export of a 3D scene to a different application not only depends on Ayam but also on the importing application. For instance, many applications claim to read files in the Wavefront OBJ format but only import polygonal data or, even worse, only triangles from such files. By default, Ayam tries to preserve as much information / design intent as possible in the respective export format leading e.g. to the use of NURBS in Wavefront OBJ files. Consequently, to successfully transfer an Ayam scene to a different application, in some cases, manual conversion of the NURBS objects in the Ayam scene to polygonal geometry may be necessary. There is a script provided that helps in doing this ("topoly.tcl", see also section Convert Everything to Polygons).

Ayam is not perfect either, as in most import options material and animation data is completely ignored.

The following table gives an overview of the file format versions supported by the various import and export plugins. Import of files from a different version should be considered unsupported.

The next sections document the various import and export plugins in detail.

7.3 RenderMan Interface Bytestream (RIB) Import

Using the "rrib" (for Read RIB) plugin RenderMan Interface Bytestreams of version 3.0 can be imported into Ayam. This plugin is based on the Affine library by Thomas E. Burge. Start importing a RIB using the menu entry "File/Import/RenderMan RIB" (if this menu entry is not available, the rrib plugin must be loaded using the menu entry "File/Load Plugin" first).

RIB Primitive Support

The RRIB plugin supports import of the following geometric primitives:

• Quadrics (Sphere, Disk, Cylinder, Cone, Paraboloid, Hyperboloid, Torus),
• bilinear and bicubic patches and patch meshes,
• NURBS patches (with trim curves),
• (general) polygons and (general) polygon meshes,
• subdivision meshes (with all tags).

Furthermore, the plugin supports reading of CSG, object instances, archives, light sources (including area-lights), arbitrary linear transformations (except shear transformations), arbitrary RiOptions and RiAttributes, shaders (except transformation shaders and without array arguments), arbitrary primitive variables (e.g. varying or vertex)^[∗] , and procedural objects and delayed read archives^[∗].
Texture coordinates will import as TC tags (see also section TC (Texture Coordinates) Tag). The handedness of the scene (set via RiOrientation) is tracked and converted to the right-handed default of Ayam.^[∗]

The RRIB plugin does not support reading of curves, implicit surfaces (blobby models) and calls to the RenderMan interface that are not so much useful for a RIB import like e.g. RiMakeTexture.
Unsupported geometric primitives and other calls to the RenderMan interface are silently ignored.

Also note that for NURBS patches and bicubic patch meshes, points of type "P" will be promoted to "Pw". Points of type "Pz" are not supported by the plugin. Trimming of NURBS patches by clamping their knot ranges is also not supported (however, UMM/VMM tags will be created, that contain the new knot minimum and maximum values).^[∗] See also section UMM/VMM (U/V Min Max) Tag.

Furthermore, objects of type (general) polygon and polygon mesh will always be promoted to general polygon meshes.

Object instances are resolved to normal objects while importing. Instances may be easily created again using Automatic Instancing (see section Automatic Instancing). If there are multiple objects in a RenderMan object instance, an enclosing Level object will be created.^[∗]

Procedural objects will not be evaluated, instead, RiProc objects will be created, that carry all arguments and create the same sequence of RIB requests upon export as was read upon import.

Note that in the case of serious syntactic errors of the RIB file more informative error messages are printed to the stderr channel of Ayam (which is not redirected to the Ayam console).

RIB Import Options

The RIB import may be controlled via different options:

• "ScaleFactor", determines a global scale factor to be applied to all imported objects.
• "ReadFrame", specifies the number of the frame in the RIB to read. A value of -1 means, all frames are to be read. If a frame number is specified and this frame does not show up in the RIB as "FrameBegin <yournumber>" nothing will be imported.
• "ReadCamera": if this is switched on, a Camera object will be created when the RIB plugin encounters a "WorldBegin". You may drag this camera object onto a perspective View object in Ayam after import to see through the camera of the imported RIB.
• "ReadOptions", controls whether RiOptions are to be imported from the RIB to the scene. Note that those RiOptions will overwrite the current global settings in the Ayam scene.
• "ReadLights", if this is enabled the lights from the RIB will be imported.
• "ReadMaterial", controls whether material objects are to be created for the imported objects. All material objects are created in a special level named "Materials" in the top level of the scene. The plugin tries to keep the number of generated material objects as low as possible by comparing with already existing materials in this level. This also works with material objects that exist before the RRIB plugin is invoked (as long as they reside in this special level).
• "ReadPartial", this option is useful if you want to import partial RIBs (e.g. archives) that do not contain a "WorldBegin". Be careful with this option (i.e. use it only if reading of a RIB fails), as it switches reading of all types of objects on, regardless of the RIB structure.
• "ReadSTrim" if switched off, no simple trims (trims that only run along the border of a NURBS patch and actually do not trim the surface) will be imported if they are the only trim curves.
• "RescaleKnots" allows to rescale the knot vectors of NURBS patches and trim curves so that the distances between different knots are not smaller than the given value. Using a value of 1.0e-04 leads to NURBS that may be safely drawn using GLU. The default value 0.0 means no scaling.
• "Progress": displays the progress of the import in terms of line numbers of the file to import (archives do not advance the progress).

7.4 RenderMan Interface Bytestream (RIB) Export

RenderMan Interface Bytestream (RIB) export is the most important export module of Ayam and in fact justifies its existence. All features of the Ayam object and scene structure are supported (hierarchy, CSG, instances, materials, lights etc.). Furthermore, Ayam also supports direct rendering from view windows, rendering in multiple passes for shadow maps, and permanent previews (where a RenderMan renderer is directly coupled to an Ayam view window).

The documentation on RIB export is spread over the Ayam documentation, this section gives some general information and otherwise just points to the real documentation sections.

RIB export is always available, it does not need a plugin to be loaded. The corresponding main menu entry is "File/Export/RenderMan RIB" and the corresponding keyboard shortcut is <Ctrl+E>. To control the RIB export and rendering, many options exist that are documented in section RIB-Export preferences.

There are also some special ways to export RIBs available in the main menu: "Special/RIB-Export"; this is documented in section Special Menu.

Ayam can not only export scenes as RIB but also call various RenderMan renderers to directly render the exported RIB files to the screen or to an image file. Documentation on how to export/render directly from a view window can be found in section View Menu.

Invoking RIB export is also possible using the scripting interface, see the section RIB export for more information.

RIB export always honors "NoExport" tags and the "HideChildren" attribute.

7.5 Mops Import

In older versions of Ayam, Mops scenes could be imported using the main menu entry: "File/Import Mops". Since Ayam 1.13 Mops import is a plugin named "mopsi". After loading the plugin, Mops scenes may be imported using the main menu entry "File/Import/Mops".

Ayam is able to import most elements of a Mops scene except for RiAttributes attached to arbitrary geometric objects, because attributes and shaders are managed by material objects in Ayam. However, if a Mops object has a surface or displacement shader, a material object with the shaders from the Mops object and its RiAttributes will be automatically created and linked with the geometric object while importing. Only Mops objects with surface or displacement shaders are considered because otherwise a material object would have to be created for every imported Mops object. The material objects are named "mat0", "mat1" and so on. Make sure, that the current scene in Ayam does not contain material objects with those names, otherwise Mops import will not be able to create material objects for the scene to import.

The import options "ResetDM" and "ResetST" control, whether GLU display mode and tolerance settings (see sections NCurveAttr, and NPatchAttr for more information about display mode and tolerance) of NURBS primitives should be reset to using global preference values (the default in Ayam) instead of using the values from the Mops scene file.

7.6 AutoCAD DXF Import

The "dxfio" plugin allows to import AutoCAD DXF (drawing interchange format) files into Ayam with the help of the Dime library (from Systems in Motion, Kongsberg SIM AS, Norway). This plugin only supports files up to version 14 of the file format.

Start importing a DXF file using the main menu entry "File/Import/AutoCAD DXF" (if this menu entry is not available, the dxfio plugin must be loaded using the menu entry "File/Load Plugin" first).

Note that the entire DXF file is read into memory before any geometry is created.

DXF Entity Support

The DXF import plugin supports reading of the following DXF entities: 3DFACE, ARC, CIRCLE, ELLIPSE, LINE, SOLID, TRACE, BLOCK, INSERT, POLYLINE, LWPOLYLINE, and SPLINE. Entities not listed here will be silently ignored.

3DFACE entities are imported as PolyMesh objects if either only the first three points are unique (the entity describes a triangle) or the face is planar else as BPatch objects.

ARC, CIRCLE, and ELLIPSE entities will be read as NCircle objects with corresponding "TMin", "TMax" parameters (for arcs and ellipses) and scale transformation values (for ellipses) set.

POLYLINE entities are completely supported:

• Polylines will be imported as NCurve objects;
• PolyMeshes and PolyFaceMeshes will be imported as PolyMesh objects;
• B-Spline and Bezier surfaces will be imported as NPatch objects.

LINE, LWPOLYLINE, and SPLINE entities will be imported as NCurve objects.

SOLID and TRACE entities are imported as BPatch objects.

BLOCK and INSERT entities will be converted to appropriate master (referenced) and instance objects (references).

Bulges and extrusions are not supported.

The following table comprehensively lists the supported DXF entities and their Ayam counterparts that will be created upon import.

DXF Import Options

The DXF import may be controlled via different options:

• "FileName": is the path and name of the DXF file to import.
• "ReadCurves": if this is disabled, no freeform curves will be imported.
• "ScaleFactor": allows to apply a scaling factor to all imported objects.
• "ReadLayers": using this import option, a single layer or a range of layers may be selected for import. By default, all entities from all layers will be imported.
• "RescaleKnots": allows to rescale the knot vectors of imported NURBS curves so that the distances between different knots are not smaller than the given value. A "RescaleKnots" value of 1.0e-04 leads to NURBS that may be safely drawn using GLU. The default value 0.0 means no scaling.
• "Progress": displays the progress of the import; from 0 to 50 percent, Dime is reading the DXF file; from 50 to 100 percent, the dxfio plugin is converting the DXF entities to Ayam objects.

7.7 AutoCAD DXF Export

The "dxfio" plugin allows to export Ayam scenes to AutoCAD DXF (drawing interchange format) files with the help of the Dime library (from Systems in Motion, Kongsberg SIM AS, Norway).

Start exporting to a DXF file using the main menu entry "File/Export/AutoCAD DXF" (if this menu entry is not available, the dxfio plugin must be loaded using the menu entry "File/Load Plugin" first).

Note that the entire Ayam scene is converted to a corresponding DXF model in memory before it is written to the DXF file.

Ayam only creates entities of type POLYLINE and SPLINE and misses very much information that could be saved to other formats (e.g. normals and texture coordinates). Therefore, the DXF export format should be avoided if possible.

Ayam Object and Properties Support

The export functionality of the dxfio plugin currently covers export of all boxes, quadrics, NURBS, PolyMeshes, instances, clones, script objects (of type "Create" or "Modify"), and objects that may be converted to NURBS curves or surfaces or to PolyMeshes. However, all boxes and quadrics will always be converted to NURBS surfaces and NURBS surfaces will be tesselated to PolyMeshes for export.

The scene hierarchy and CSG operations are fully ignored, all objects will be written as if combined by the union operator.

All transformations will be applied to the control points of the exported objects.

PolyMesh objects will be exported to POLYLINE (subtype PolyFaceMesh) entities. If a PolyMesh object contains faces with holes or with more than four points, it will be tesselated for export. Eventually existing normals will not be exported.

NURBS curves will be exported as SPLINE entities.

Instance objects are resolved for export.

Light sources, as well as Cameras, Views, and Materials are not exported.

Clamping the knot ranges of NURBS curves or surfaces via UMM/VMM tags is not supported. Texture coordinates will not be exported.

DXF Export Options

The DXF export may be controlled via different options:

• "FileName": is the path and name of the DXF file to export to.
• "ScaleFactor": allows to apply a scaling factor to all exported objects.
• "WriteSelected": exports only the selected objects.
• "ObeyNoExport": ignores all objects with "NoExport" tags.
• "IgnoreHidden": ignores all hidden objects.
• "WriteCurves": if this is disabled, no freeform curves will be exported.
• "TopLevelLayers": controls whether the top level Level objects in the Ayam scene to be exported should be interpreted as layers. If this option is enabled, all objects in these levels will be placed on the respective layer. Objects that are not in one of those levels will be written to the default layer. Furthermore, top level object names will become layer names.
• "Progress": displays the progress of the export; from 0 to 50 percent, the dxfio plugin is converting the Ayam objects to DXF entities; from 50 to 100 percent, Dime is writing the DXF file.

7.8 Wavefront OBJ Import

Since Ayam 1.8.3 a Wavefront OBJ (version 3.0) import facility is available and since Ayam 1.13 it is a plugin ("objio") that needs to be loaded before import. Since Ayam 1.34 also materials from accompanying MTL files can be imported. The corresponding main menu entry is "File/Import/Wavefront OBJ" (if this menu entry is not available, the objio plugin must be loaded using the menu entry "File/Load Plugin" first).

Wavefront OBJ Statement Support

Wavefront OBJ import supports reading of polygonal lines and faces with vertex normals and texture coordinates (the latter are read as primitive variable tags); statements: v, vt, vn, l, f.

Furthermore, freeform curves and surfaces (NURBS) with trim curves and with texture coordinates (again read as primitive variable tags) are supported; statements: vp, cstype, deg, curv, curv2, surf, parm, trim, hole, end.

Freeform curves and surfaces of basis type bmatrix, cardinal and taylor are currently not supported. Also, import of special curves (statement scrv) and points (statement sp) as well as surface connectivity information (statement con) are currently not supported.

Furthermore, trimming of freeform curves and surfaces by additionally clamping their knot ranges will be realized by UMM/VMM tags, that contain the new knot minimum and maximum values.^[∗] See also section UMM/VMM (U/V Min Max) Tag.

The grouping statements g and o are supported as means to import object names.

Since Ayam 1.34 materials from accompanying MTL files can be imported; statements: mtllib, usemtl. See also section Wavefront Material Import.

Unsupported statements will be silently ignored.

Wavefront OBJ import expects the file to be syntactically correct. The plugin is not very good in detecting and reporting errors. If the import fails, a third party tool should be used first to check whether the Wavefront OBJ file is valid at all.

Also, note that the objio plugin supports Wavefront version 3.0 syntax only, files that use older syntax will not be imported correctly.

Wavefront OBJ Import Options

The following options control the Wavefront OBJ import process:

• "FileName": is the name of the Wavefront OBJ file (version 3.0)
• "MergeFaces": controls whether consecutive polygonal faces should be merged into a single PolyMesh object for import. Note that the merged PolyMesh objects probably needs to be optimized if there are vertices used by multiple faces (main menu "Tools/PolyMesh/Optimize").
• "MergePVTags": controls whether the PV tags of PolyMesh objects should be merged as well if they are subject to automatic merging (see above).
• "ReadCurves": if this is disabled, no freeform curves will be imported. This option does not influence the import of trim curves.
• "ReadSTrim": if switched off, no simple trims (trims that only run along the border of a NURBS patch and actually do not trim the surface) will be imported if they are the only trim curves.
• "ReadTexCoords": controls if and how texture coordinates will be imported:
  • "None": disables texture coordinate import,
  • "Separately": leads to texture coordinates in two primitive variables ("s" and "t") which can be used directly by standard RenderMan shaders (e.g. "paintedplastic"),
  • "Combined": leads to texture coordinates in one primitive variable which would be easier to be used by exports to non RIB formats.
• "ReadMaterials": toggles reading of MTL files.
• "UseMaterials": switches, whether or not imported geometric objects will be connected to corresponding materials.
• "RescaleKnots": allows to rescale the knot vectors of NURBS curves, patches, and trim curves so that the distances between different knots are not smaller than the given value. A "RescaleKnots" value of 1.0e-04 leads to NURBS that may be safely drawn using GLU. The default value 0.0 means no scaling.
• "ScaleFactor": allows to apply a scaling factor to all imported objects.
• "RationalStyle": determines how rational coordinates are stored in the file to be imported (see also section Rational Style);
• "DefaultIllum": specifies the default illumination model to use, when reading materials without illum statements. See also section Wavefront Material Import.
• "Progress": displays the progress of the import; from 0 to 100 percent, the objio plugin is reading lines from the Wavefront OBJ file and creating Ayam objects. The number may be a bit off occasionally, as the progress meter just counts lines and assumes a fixed medium line length of 28 characters.

Wavefront Material Import

Import of Wavefront MTL files is available since Ayam 1.34. The import of an MTL file is usually triggered by the corresponding mtllib statement in a Wavefront OBJ file, but MTL files can also be imported directly.
Regardless of how it was started and whether or not any objects from the corresponding Wavefront OBJ file actually use these materials, the material import always creates Ayam Material objects for every material in the MTL file.

The following material statements are supported: newmtl, Ka, Kd, Ks, Tf, d, Ns, Ni, map_Ka, map_Kd, map_Ks, map_Ns, map_d, disp, bump, refl, illum.

Decals (statement decal) are not supported.

Color statements (Ka, Kd, Ks, and Tf) support the RGB and CIEXYZ color spaces, but values declared in CIEXYZ will be converted to RGB for import. Spectral curves specified via the spectral option are not supported.

The dissolve statement (d) is fully supported, this includes the -halo option.

Import of bump maps (statement bump) supports the bump multiplier option (-bm).

All other texture map options (-blendu, -blendv, -cc, -clamp, -mm, -imfchan, -o, -s, -t, -texres) are not supported.

The only reflection map type supported by the refl statement is sphere ("lat-long" in RenderMan terms).

All normal illumination models (0-9) are fully supported, but 8 will be mapped to 3 and 9 to 4.

Materials not specifying an illumination model will use a model selected by the following set of rules:

• if a reflection map is used (refl statement), the model is at least 3,
• if the material is transparent (d statement), the model is at least 4,
• if the optical density is specified (Ni statement), the model is 7.

These rules can be overridden by the "DefaultIllum" import option.

Note that a wrongly specified illumination model can lead to the discarding of parameters that are specified in the MTL file but unused by the illumination model.

The various illumination models are realized through a set of RenderMan surface and displacement shaders that are distributed in the "ayam/scn/shaders" directory. These are named RSmtli0.sl to RSmtli7.sl and RSmtld.sl and need to be compiled for the respective target renderer before possible usage.
From 0 to 7, the illumination models get more capable, complex, have more parameters but also require more rendering time.
As the various shaders may also be used outside the Wavefront OBJ import context, they are explained in greater detail in the next sections.

RSmtli0 – Constant

This shader implements the most basic illumination model for constant color, i.e. ignoring any light source information, but nevertheless supporting opacity and bump mapping albeit the bump mapping only serves to distort the normal for the dissolve halo effect. Rendered objects will appear flat. A similar standard RenderMan shader would be constant.

RSmtli1 – Diffuse

The illumination model of this shader adds a diffuse term, i.e. uses light sources. Rendered objects will appear three dimensional, a similar standard RenderMan shader would be matte.

RSmtli2 – Specular

This shader adds specular highlights whose acuteness can be controlled via a parameter (Ns). Rendered objects will appear as if made from plastic, similar standard RenderMan shaders would be plastic or paintedplastic.

RSmtli3 – Reflection

This shader adds reflections from either ray tracing or a reflection map, a similar standard RenderMan shader would be shinymetal.

RSmtli4 – FakeGlass

This shader adds specular highlight saving to the opacity formula and can therefore be used to approximate glass without ray tracing. However, objects behind the fake glass will not appear distorted and the color of the transmitted light will also not be influenced.

RSmtli5 – FresnelReflect

This shader improves the raytraced reflections at grazing angles by employing the Fresnel equations.

RSmtli6 – Raytracing

This shader implements full ray traced reflections and refractions with coloring of transmitted light but without any Fresnel effects.

RSmtli7 – Fresnel

This shader improves the raytraced reflections and refractions at grazing angles by employing the Fresnel equations.

See also the image above, rendered with BMRT 2.6, scene distributed with Ayam as "mtls.ay".

RSmtl Shaders and Material Attributes

Note that in contrast to established use in other RenderMan shaders, the RSmtlix surface shaders completely ignore the standard color and opacity attributes. To avoid confusion it is therefore suggested to set one component of these attributes to -1 for Ayam Material objects that make use of one of these shaders. The color preview of the shaded drawing mode of Ayam is aware of this and will use the color set with the Kd surface shader parameter instead.

RenderMan Renderer Support

Not all RSmtl shaders are supported by all RenderMan renderers. The RSmtli0 to RSmtli4 shaders may be used with all renderers including pure REYES renderers (e.g. Aqsis or Pixie with the stochastic hider) whereas the other shaders, RSmtli5 to RSmtli7, require ray tracing capable renderers, (e.g. BMRT or Pixie with the raytrace hider).
When using a REYES renderer with the RSmtli3 shader, the "refl_map" parameter must be set.

7.9 Wavefront OBJ Export

Since Ayam 1.7, it is possible to export scenes or objects to the Wavefront OBJ format (version 3.0). Since Ayam 1.13, Wavefront OBJ export is a plugin ("objio") that needs to be loaded before export. The corresponding main menu entry is "File/Export/Wavefront OBJ" (if this menu entry is not available, the objio plugin must be loaded using the menu entry "File/Load Plugin" first).

Ayam Object and Properties Support

The Wavefront export currently supports the following objects:

• NCurve and objects that may be converted to NCurve objects (e.g. ICurve, ConcatNC, ExtrNC),
• NPatch (with trim curves) and objects that may be converted to NPatch objects (e.g. BPatch, PatchMesh, Revolve, Sweep, Extrude, Skin, Cap, Gordon, Birail1, Birail2, Text),
• Quadrics will be automatically converted to NURBS surfaces,^[∗]
• PolyMesh and objects that may be converted to PolyMesh objects (e.g. MetaObj), faces with holes are not supported by the Wavefront OBJ format and will be tesselated to triangles for export automatically,
• Box (as six polygonal faces),
• Instance, Clone, Mirror; those will be resolved to normal objects for export as Wavefront OBJ does not support referenced geometry.

The hierarchy of the Ayam scene will be squashed to one level, transformations will be properly delegated to the child objects.

CSG operations are fully ignored, all objects will be written as if combined by the union operator.

The Wavefront OBJ export supports material information which gets written to accompanying MTL files.^[∗] See also section Wavefront Material Export.

Texture coordinates from primitive variable tags will be exported.^[∗] Also TC tags are supported, but PV tags take precedence.^[∗]

UMM/VMM tags are used to trim the knot vectors of exported NURBS objects.^[∗] See also section UMM/VMM (U/V Min Max) Tag.

Light sources, as well as Cameras, and Views will not be exported.

Object names will be exported as o statements.

Wavefront OBJ Export Options

The following parameters control the Wavefront OBJ export:

• "FileName": is the filename of the Wavefront OBJ or MTL file;
• "WriteHeader": controls export of a header;
• "Header": allows to adjust the content of the header, the place holders %d, %t, and %u will be replaced by the current date, time, and user name respectively;
• "WriteSelected": exports only the currently selected object(s);
• "TessPoMesh" automatically tesselates all PolyMesh objects to triangles for export;
• "WriteCurves": toggles writing of NURBS curves and NURBS curve providing objects to the exported Wavefront OBJ file (This option does not influence the export of trim curves.);
• "WriteMaterials": toggles export of an accompanying MTL file, containing all materials used by the exported geometric objects, and prepends all objects in the OBJ file with a corresponding usemtl statement, which will be empty for objects without material if there was a material set before;
• "DefaultIllum": determines the illumination model to be used for all Material objects with unsupported surface shaders;
• "ScaleFactor": allows to apply a scaling factor to all exported objects;
• "RationalStyle": determines how to write rational coordinates (see also section Rational Style);
• "Progress": displays the progress of the export; from 0 to 100 percent, the objio plugin is writing the Ayam objects to the Wavefront OBJ file.

Wavefront Material Export

Export of Ayam Material objects to MTL files is available since Ayam 1.34. The creation of a MTL file can be triggered by the "WriteMaterials" export option or by using a export filename with an .mtl-extension. In the latter case, all Material objects in the scene will be written to the MTL file (or just the selected Material objects, if the "WriteSelected" export option is enabled).

All materials created by a previous import of a Wavefront material are fully supported. See also section Wavefront Material Import.

In addition, materials using one of the following RenderMan standard surface and displacement shaders are supported: "constant", "matte", "plastic", "paintedplastic", "metal", "shinymetal", "bumpy". Furthermore, there is support for the "glass" surface shader with the following parameters: "Ka", "Kd", "Ks", "roughness", "specularcolor", and "eta".

The following table comprehensively lists the illumination model used by the respective RenderMan surface shader upon export.

If any of these materials has a opacity set, a corresponding dissolve statement (d) will be exported.

Materials with unsupported shaders will be written using a "Kd" statement with values taken from the material Color attribute, a "d" (dissolve) statement with values taken from the material Opacity attribute (if not set to fully opaque), and a "illum" statement according to the "DefaultIllum" export option.^[∗]

7.10 3DMF (Apple) Import

Using the "mfio" plugin scenes may be imported from the 3DMF format (QuickDraw 3D Metafile) from Apple with the help of a free 3DMF parser created by Duet Development Corp. and distributed by Apple. Start importing a 3DMF file using the menu entry "File/Import/Apple 3DMF" (if this menu entry is not available, the mfio plugin must be loaded using the menu entry "File/Load Plugin" first).

The mfio plugin only supports the 3DMF version 1.0!

3DMF Primitive and Attribute Support

The mfio plugin supports import of the following geometric primitives:

• Polyline, Triangle, TriGrid, Polygon, general Polygon, Box,
• NURBS curve, NURBS surface (with trim curves),
• Ellipsoid, Cylinder, Cone, Disk, and Torus.

The following table comprehensively lists the supported 3DMF primitives and their Ayam counterparts that will be created upon import.

The following transformations are supported in 3DMF import:

• Scale,
• Translate,
• Rotate, RotateQuaternion, RotateAxis (if axis is X, Y, or Z).

Furthermore, the import plugin reads the structure of the scene from Container objects. Reference objects will be resolved to normal objects while importing. Instances may be easily created again using Automatic Instancing (see section Automatic Instancing).

Support for import of lights, camera attributes as well as material attributes other than material color and opacity is currently not available.

3DMF Import Options

The following parameters, additionally, control the 3DMF import:

• "FileName": is the filename of the 3DMF file to import;
• "ScaleFactor": The "ScaleFactor" option allows to apply a scaling factor to all imported objects.
• "ReadCurves": If the "ReadCurves": import option is switched off, no curves will be imported. This option does not influence the import of trim curves.
• "ReadSTrim" if switched off, no simple trims (trims that only run along the border of a NURBS patch and actually do not trim the surface) will be imported if they are the only trim curves.
• "RescaleKnots": allows to rescale the knot vectors of NURBS curves, patches, and trim curves so that the distances between different knots are not smaller than the given value. A "RescaleKnots" value of 1.0e-04 leads to NURBS that may be safely drawn using GLU. The default value 0.0 means no scaling.

7.11 3DMF (Apple) Export

Using the "mfio" plugin scenes may be exported to the 3DMF format (QuickDraw 3D Metafile) from Apple with the help of a free 3DMF parser created by Duet Development Corp. and distributed by Apple. Start exporting to a 3DMF file using the menu entry "File/Export/Apple 3DMF" (if this menu entry is not available, the mfio plugin must be loaded using the menu entry "File/Load Plugin" first).

The mfio plugin only supports the 3DMF version 1.0!

Ayam Object and Properties Support

The mfio export supports the following geometric objects:

• NURBS curve and NURBS surface (with trim curves) including all NURBS curve/surface providing objects, such as ICurve, Skin etc.,
• Sphere, Disk, Cone, Cylinder, Torus,
• Box, and PolyMesh.

Objects of types not listed here will be converted to NURBS (if possible) or to PolyMesh objects automatically for export.

All transformations are supported and will be written as Translate, Rotate, and Scale transformations, respectively.

All Instance objects will be resolved for export. Level objects (regardless of type) will be written as Container objects.

If an object has a material, the color and opacity of the material will be written as DiffuseColor and TransparencyColor, if the respective red color component has a value different from -1.

Support for export of lights, camera attributes as well as material attributes other than material color and opacity is currently not available.

Trim Curves Support

The 3DMF file format specification for version 1.0 is unfortunately very terse, when it comes to trim curves. There is no clearly defined way of specifying them in conjunction with their respective NURBS surface. Furthermore, the method presented here is the only way that works with the free provided 3DMF parser. Trimmed NURBS patches will be written by Ayam like this:

Container (
        NURBPatch ( ...
        )
        [transformations & attributes of NURBS patch]
        TrimCurves ( )
        NURBCurve2D ( ...
        )
        Container (
                NURBCurve2D ( ...
                )
                NURBCurve2D ( ...
                )
        )
)

1. There will always be an enclosing Container for a NURBS patch.
2. If the patch is trimmed, after the NURBPatch or potentially present transformations and attributes of the patch, a TrimCurves element will follow (which does not contain the trim curves but is empty).
3. The trim curves follow now as 2D NURBS curves (NURBCurve2D objects for simple trims) or Container objects (for trim loops) with multiple 2D NURBS curves until the end of the enclosing container.
4. The transformation attributes of the trim curves will be applied to the NURBS curve control points for export (there will be no transformations or attributes for the trim curve elements).

The Ayam 3DMF import expects the trim curves to be delivered in this manner and can then indeed read them back accurately.

3DMF Export Options

The following parameters, additionally, control the 3DMF export:

• "FileName": is the filename of the 3DMF file to export;
• "WriteBinary": This option controls whether the text version or the binary version of the 3DMF file format should be used for export.
• "ScaleFactor": This option allows to apply a scaling factor to all exported objects.
• "WriteSelected": exports only the selected objects.
• "WriteCurves": If this option is disabled, no curves will be written to the exported 3DMF file. This option does not influence the export of trim curves.

7.12 3DM (Rhino) Import

Since version 1.8.2 Ayam contains a plugin named "onio" that may import scenes from the Rhino 3DM file format using the OpenNURBS toolkit (hence the name of the plugin onio – OpenNURBS IO) by Robert McNeel & Associates.

Start importing from a Rhino 3DM file using the menu entry "File/Import/Rhino 3DM" (if this menu entry is not available, the onio plugin must be loaded using the menu entry "File/Load Plugin" first).

The onio plugin only supports import of 3DM files of version 3.0 and earlier.

3DM Object Support

The import functionality of the onio plugin currently covers import of all NURBS and BRep objects and objects that may be converted to NURBS with routines from the OpenNURBS toolkit (those objects are: PolylineCurve, PolyCurve, LineCurve, ArcCurve, CurveOnSurface, RevSurface, SumSurface, and PlaneSurface). References will be resolved. Names will be imported, but converted to an ASCII representation. Since Ayam 1.8.3 also Mesh objects will be imported to PolyMesh objects, texture coordinates will be read and appropriate PV tags will be created for them.

The following table comprehensively lists the supported Rhino 3DM primitives and their Ayam counterparts that will be created upon import.

3DM Import Options

The 3DM import process is controlled by the following options:

• "ScaleFactor": This option allows to apply a scaling factor to all imported objects.
• "Accuracy": This option controls the tolerance of OpenNURBS internal operations, in this case the value is mostly used for conversion operations to the NURBS form.
• "ReadCurves": If this option is switched off, no curves will be imported. This option does not influence the import of trim curves.
• "ReadLayers": Using this import option, a single layer or a range of layers may be selected for import. By default, all objects from all layers will be imported.
• "ReadSTrim": This option helps to ignore single bounding trim loops of NURBS surfaces. Importing this single bounding trim loop would just make the Ayam scene more complex than needed in many cases. If "ReadSTrim" is switched off, no simple trims (trims that only run along the border of a NURBS patch and actually do not trim the surface) will be imported if they are the only trim curves.
  This option replaces the "IgnoreFirstTrim" import option available before Ayam 1.13 with slightly different semantics.
• "RescaleKnots": allows to rescale the knot vectors of NURBS curves, patches, and trim curves so that the distances between different knots are not smaller than the given value. A "RescaleKnots" value of 1.0e-04 leads to NURBS that may be safely drawn using GLU. The default value 0.0 means no scaling. Since Ayam 1.13 also eventually present trim curves will be scaled properly to the new knot ranges of NURBS patches.
• "Progress": displays the progress of the import; from 0 to 50 percent, OpenNURBS is reading the 3DM file into memory; from 50 to 100 percent, the onio plugin is converting the 3DM objects to Ayam objects.

7.13 3DM (Rhino) Export

Since version 1.8.2 Ayam contains a plugin named "onio" that exports scenes to the Rhino 3DM file format using the OpenNURBS toolkit (hence the name of the plugin onio – OpenNURBS IO) by Robert McNeel & Associates.

Start exporting to a Rhino 3DM file using the menu entry "File/Export/Rhino 3DM" (if this menu entry is not available, the onio plugin must be loaded using the menu entry "File/Load Plugin" first).

The onio plugin exports 3DM files of version 3.0.

Ayam Object and Properties Support

The export functionality of the onio plugin currently covers export of all boxes, quadrics, NURBS, polymeshes, instances, clones, script objects (of type "Create" or "Modify") and objects that may be converted to NURBS curves or surfaces.

Even though export of planar cap surfaces of various tool objects is fully supported, the export of general trimmed NURBS patches is not well supported. This is because of a missing feature (pushing up 2D trim curves to 3D curves for arbitrary NURBS surfaces) in the OpenNURBS toolkit. A coarse polygonal 3D representation of the 2D trim curves will be created automatically, so that general trimmed NURBS patches may be exported, albeit with lower quality and bigger file size as would be necessary.^[∗]

UMM/VMM tags are used to trim the knot vectors of exported NURBS objects.^[∗] See also section UMM/VMM (U/V Min Max) Tag.

Since the Rhino 3DM file format does not support hierarchy and transformation attributes per object, the hierarchy of the Ayam scene will be squashed and all transformation attributes will be applied to the control points of the objects for export. CSG operations are fully ignored, all objects will be written as if combined by the union operator. Furthermore, all instance objects will be resolved to normal objects.

All objects will be written to the first layer, the default layer (unless the "TopLevelLayers" option is used). Object names will be exported as well. Names of level objects will be prepended to the names of their child objects. The object hierarchy:

+-Arm(Level)
  |-MySphere(Sphere)
  \-MyCylinder(Cylinder)

3DM Export Options

The 3DM export process is controlled by the following options:

• "ScaleFactor": The "ScaleFactor" option allows to apply a scaling factor to all exported objects.
• "Accuracy": The "Accuracy" option controls the tolerance of internal OpenNURBS operations (currently those are: pushing up 2D trim curves to 3D curves and checking NURBS surfaces for planarity).
• "WriteSelected": exports only the selected objects.
• "ObeyNoExport": ignores all objects with "NoExport" tags.
• "IgnoreHidden": ignores all hidden objects.
• "WriteCurves": If this option is disabled, no curves will be written to the exported Rhino 3DM file. This option does not influence the export of trim curves.
• "QuadAsBRep": If this option is enabled spheres, cylinders, cones, and torii will not be exported as collection of NURBS surfaces (as converted by Ayam) but as BRep objects (as converted by the OpenNURBS toolkit). However, not all features of the quadric objects will be translated in this case:
  • The BRep sphere does not support ZMin, ZMax, and ThetaMax.
  • The BRep cylinder does not support ThetaMax (base caps will be created if the cylinder is closed).
  • The BRep cone does not support ThetaMax (a base cap will be created, if the cone is closed).
  • The BRep torus does not support PhiMin, PhiMax, and ThetaMax.
  The "QuadAsBRep" option has no effect on the export of disks, hyperboloids, and paraboloids. Those will always be exported as NURBS surfaces.
• "TopLevelLayers": controls whether the top level Level objects in the Ayam scene to be exported should be interpreted as layers. If this option is enabled, all objects in these levels will be placed on the respective layer. Objects that are not in one of those levels will be written to the default layer. Furthermore, top level object names will become layer names.
• "Progress": displays the progress of the export; from 0 to 50 percent, the onio plugin is converting the Ayam objects to 3DM objects; from 50 to 100 percent OpenNURBS is writing the 3DM file.

7.14 X3D (Web3D) Import

Since version 1.13 Ayam provides a plugin named "x3dio" that may import scenes from the XML based X3D file format published by the Web3D Consortium. The XML parser used in this plugin is based on Expat and SCEW.

Binary and compressed versions of X3D, as well as VRML files are not supported. Only pure XML files are read by the x3dio plugin.

Start importing from a Web3D X3D file using the menu entry "File/Import/Web3D X3D" (if this menu entry is not available, the x3dio plugin must be loaded using the menu entry "File/Load Plugin" first).

X3D Element Support

The import functionality of the x3dio plugin currently covers import of the following X3D elements (grouped by components):

• Geometry3D: Box, Sphere, Cylinder, Cone, ElevationGrid, Extrusion, IndexedFaceSet, IndexedTriangleSet, IndexedTriangleStripSet, IndexedTriangleFanSet, TriangleSet, TriangleStripSet, TriangleFanSet, IndexedLineSet, and LineSet.

  Cylinders with just one cap are imported as two objects (a Cylinder and a Disk). In all other cases and also for Cones, the "Closed" attribute of the Ayam object is set according to the cap information of the X3D element.

  ElevationGrids are imported as bilinear patch meshes.

• Geometry2D: Arc2D, ArcClosed2D, Circle2D, Disk2D, Polyline2D.

  Arcs and Circles are imported as NCircle objects. Closed arcs and Polylines are imported as NURBS curves. Disks with an inner radius > 0.0 are imported as flat Hyperboloids (otherwise as Disks).

• NURBS: NurbsCurve, NurbsCurve2D, NurbsPatchsurface, NurbsTrimmedSurface, Contour2D, ContourPolyline2D, NurbsSweptSurface, NurbsSwungSurface, NurbsSet.

  All NURBS elements are fully supported.

• CAD: QuadSet, IndexedQuadSet, CADLayer, CADAssembly, CADPart, CADFace.

  CADLayer objects will be imported as top level Level objects. CADAssembly and CADPart objects will be imported as level objects.

• Light sources: DirectionalLight, PointLight, SpotLight.

  The lights will be directly mapped to the standard RenderMan light sources distant, point, and spot, respectively. Therefore, the "radius" and the "attenuation" attributes of point and spotlights are not supported. However, point and spotlights still have a quadratic falloff with distance.

• Navigation: Viewpoint.

  Viewpoint elements will be imported as view objects (with corresponding view window) or camera objects depending on the "ReadViewpoints" import option.

• Non geometric / Scene structure: Transformation, Shape, Group, StaticGroup, Inline.

  Shear transformations are not supported.

  The semantics for inlining are currently not fully standards compliant. By default, DEFs in inlined files live in their own namespace. It is not possible to USE a DEF from an inlined file in the inlining file. However, if the "MergeInlineDefs" import option is switched on, all DEF namespaces (of inlining and inlined files) will be merged into one big namespace. Now it would be possible to USE a DEF from an inlined file in the inlining file. But beware, this only works correctly, if the DEF names in all the files are unique. It is not possible to transfer single definitions from an inlined file to the inlining file or from the inlining file to the inlined file.

  Also note: Inline URLs that do not point to the file system are not supported.

Unsupported X3D elements will be silently ignored. Prototyping and dynamic scenes as well as scripts are not supported.

The following table comprehensively lists the supported Web3D X3D primitives and their Ayam counterparts that will be created upon import.

X3D Attribute Support

The "solid", "ccw", and "convex" attributes are always ignored.

The "DEF" and "USE" attributes are supported for all elements, however, the corresponding master-instance relationships are completely resolved upon import. Instances of objects may be easily created again using Automatic Instancing (please refer to section Automatic Instancing).

Normals will currently not be generated automatically for any X3D element and thus the "creaseAngle" attribute will be fully ignored. Note however, that if normals are specified explicitly, e.g. for an "IndexedFaceSet" element, they will be imported correctly.

Furthermore, if normals, colors, or texture coordinates are provided to an element that imports as a PolyMesh (IndexedFaceSet and the likes) proper PV (primitive variable) tags will be created.^[∗]

Moreover, if there is an index provided to the normals, colors, or texture coordinates, the relevant affected data (e.g. the vertex coordinates) will be expanded properly (as RenderMan does not support multiple different indices on the vertex related data). Note that currently the mere presence of an index will lead to this expansion. The potential normal, color, or texture coordinate index is not checked for, whether it is identical to the vertex coordinate index (and thus no expansion would be necessary in the first place).

The "DEF" attributes will be converted to object names in some cases.

X3D Import Options

The following options further control the X3D import process:

• "FileName": is the name of the X3D file to be imported
• "ReadCurves": if this is disabled, no freeform curves will be imported. This option does not influence the import of trim curves.
• "ReadViewpoints": controls whether viewpoints should be read as view, camera, or not at all.
• "ReadSTrim": if switched off, no simple trims (trims that only run along the border of a NURBS patch and actually do not trim the surface) will be imported if they are the only trim curves.
• "RescaleKnots": allows to rescale the knot vectors of NURBS curves, patches, and trim curves so that the distances between different knots are not smaller than the given value. A "RescaleKnots" value of 1.0e-04 leads to NURBS that may be safely drawn using GLU. The default value 0.0 means no scaling.
• "ScaleFactor": allows to apply a scaling factor to all imported objects.
• "RationalStyle": determines how rational coordinates are stored in the file to be imported (see also section Rational Style);
• "Progress": displays the progress of the import; from 0 to 50 percent, the x3dio plugin is reading the XML file, from 50 to 100 percent the x3dio plugin is creating Ayam objects.

7.15 X3D (Web3D) Export

Since version 1.13 Ayam provides a plugin named "x3dio" that exports scenes to the XML based X3D file format published by the Web3D Consortium. The XML parser used in this plugin is based on Expat and SCEW.

Start exporting to a X3D file using the menu entry "File/Export/Web3D (X3D)" (if this menu entry is not available, the x3dio plugin must be loaded using the menu entry "File/Load Plugin" first).

Ayam Object and Properties Support

The export functionality of the x3dio plugin currently covers export of all boxes, quadrics, NURBS, PolyMeshes, instances, clones, script objects (of type "Create" or "Modify") and objects that may be converted to NURBS curves or surfaces or to PolyMeshes (e.g. SDMesh objects).

Some NURBS tool objects can be exported as parametric NURBS nodes, e.g. Sweep objects may be exported as NurbsSweptSurface nodes.

The scene hierarchy (level objects) will be converted to a matching transform node hierarchy.

CSG operations are fully ignored, all objects will be written as if combined by the union operator.

Texture coordinates from primitive variable tags will be exported. Also TC tags are supported, but PV tags take precedence.^[∗]

Clamping the knot ranges of NURBS via UMM/VMM tags is not supported.

NURBS surfaces support XML tags to set "uTesselation" and/or "vTesselation" attributes.

PolyMesh objects will be exported to IndexedFaceSet nodes. PolyMesh faces with holes are automatically tesselated. PolyMesh faces with more than three points are tesselated if the export option "TessPoMesh" is used. All tesselated faces will be exported to a second IndexedFaceSet element.

Light sources are exported if they are point, distant, or spot lights.

Cameras and Views are exported as Viewpoint nodes. Note however, that X3D always assumes a perspective viewing transformation. This means, views of type "Front", "Side", or "Top" will not be exported properly.

Material objects are supported in a very minimalist way, i.e. only the material color will be exported as "diffuseColor" attribute. However, XML tags can be used to add more attributes or even shaders to the exported materials, see also section XML tag.

Object names will be converted to DEF attributes.

Instances can be resolved or exported as USE/DEF pairs.

Wire-frame Support

The X3D export allows to export wire-frames instead of surfaces for NPatch and PoMesh objects.

To switch an object to wire-frame export, just add a tag "AsWire" to the object.

X3D Export Options

The following parameters, additionally, control the X3D (Web3D) export:

• "FileName": is the filename of the X3D file;
• "ScaleFactor": allows to apply a scaling factor to all exported objects (this will be realized by an extra Transform-node in the scene hierarchy);
• "WriteSelected": if enabled, only the currently selected object(s) will be exported;
• "ObeyNoExport": toggles export of objects with "NoExport" tags;
• "IgnoreHidden": toggles export of hidden objects;
• "WriteCurves": toggles writing of NURBS curves and NURBS curve providing objects to the exported file (This option does not influence the export of trim curves.);
• "WriteViews": controls whether views should be exported as view points;
• "WriteParametrics": toggles writing of the following tool objects as plain NURBS surface or the following higher level primitives:
  • Revolve as NurbsSwungSurface,
  • Swing as NurbsSwungSurface,
  • Sweep as NurbsSweptSurface,
  • Extrude as NurbsSweptSurface;
• "WriteMaterials": controls whether appearance and material nodes should be exported for each shape;
• "ResolveInstances": controls whether instance objects should be resolved to normal objects or exported as DEF/USE pairs. Note, that no attempt is made to detect whether the master objects (the DEFs) will be exported for all exported instances (USE); this may happen especially in conjunction with the X3D export options "WriteSelected" or "IgnoreHidden", incomplete/erroneous X3D files may result unless the "ResolveInstances" option is switched on;
• "TopLevelLayers": arranges for all top level objects in the Ayam scene to be exported as CADLayer-nodes, instead of Transform-nodes;
• "RationalStyle": determines how to write rational coordinates (see also section Rational Style);
• "WriteX3dom": toggles X3DOM-export mode. If this option is enabled, the X3D export will
  1. first read a XHTML template file from the export target directory (named "x3dom-template.xhtml"),
  2. then inject the scene to be exported into the X3D "<Scene>"-tag of the template (already present child elements of this tag will be preserved),
  3. add width and height of the view window that was exported last as attributes to the "<X3D>"-tag,
  4. and finally write the XHTML document to the file specified via the "FileName" export option.
• "Progress": displays the progress of the export; from 0 to 50 percent, the x3dio plugin is creating a XML document in memory and from 50 to 100 percent this XML document will be written to the X3D file.