Next Previous Contents

## 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 automatically load the matching plugin (`"dxfio"`) and open the import (or export) options dialog with the `"FileName"` option already set to the filename chosen before. This feature is available since Ayam 1.13 and 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.

Feature | RIB | OBJ | 3DMF(Apple) | DXF | 3DM(Rhino) | X3D
Quadrics | Yes | No | Yes | No | Yes | Yes
Trimmed NURBS | Yes | Yes | Yes | No | Yes | Yes
Parametrics | No | No | No | No | No | Yes
Curves | No | Yes | Yes | Yes | Yes | Yes
Transformations | Yes | No | Yes | No | No | Yes
Hierarchy | Yes | No | Yes | No | No | Yes
Instances | Yes | No | No | No | No | No
CSG | Yes | No | No | No | No | No

Ayam Features Supported by 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.

Feature | RIB | OBJ | 3DMF(Apple) | DXF | 3DM(Rhino) | X3D
Quadrics | Yes | No1 | Some4 | No2 | Some4 | Some4
Trimmed NURBS | Yes | Yes | Yes | No2 | Yes | Yes3
Parametrics | No1 | No1 | No1 | No2 | No1 | Some5
Curves | No | Yes | Yes | Yes | Yes | Yes
Transformations | Yes | No | Yes | No | No | Yes
Hierarchy | Yes | No | Yes | No | No | Yes
Instances | Yes | No | No | No | No | Yes
CSG | Yes | No | No | No | No | No

Ayam Features Supported by Various Export Formats

1. will be converted to NURBS
2. will be converted to PolyMeshes
3. 3D trimcurves exported as PolyLines
4. some quadrics are converted to NURBS (refer to plugin documentation)
5. 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 quality of 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 as possible in the respective export format leading to the use of NURBS in Wavefront OBJ files. Consequently, to successfully transfer an Ayam scene to a different application, in some cases you may need to convert the NURBS objects in the Ayam scene to polygonal geometry before export. There is a script provided that helps you 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.

Format | RIB | OBJ | 3DMF(Apple) | DXF | 3DM(Rhino) | X3D
Version | 3.0 | 3.0 | 1.0 | 14 | 3.0 | 3.1

Supported File Format Versions Overview

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 you may import RenderMan Interface Bytestreams of version 3.0 into Ayam. Start importing a RIB using the menu entry `"File/Import/RenderMan RIB"` (if this menu entry is not available, you have to load the `"rrib"` plugin 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!), (since Ayam 1.7) arbitrary primitive variables (e.g. varying or vertex), and (since Ayam 1.9) procedural objects and delayed read archives.

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 the knot ranges is also not supported (however, since Ayam 1.9 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).

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 you specify a frame number 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) 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.

## 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). 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 The View Menu.

RIB export is also possible using the scripting interface, see section Scripting Interface.

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

Start importing a DXF file using the main menu entry `"File/Import/AutoCAD DXF"` (if this menu entry is not available, you have to load the `"dxfio"` plugin 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 Entity | Ayam Object
3DFACE | PolyMesh / BPatch
ARC | NCircle
CIRCLE | NCircle
ELLIPSE | NCircle
LINE | NCurve
SOLID | BPatch
TRACE | BPatch
POLYLINE | NCurve / PolyMesh / NPatch
LWPOLYLINE | NCurve
SPLINE | NCurve
INSERT | Instance

DXF Import Conversion Table

### 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"`: By default, all entities from all layers will be imported. Using the `"ReadLayers"` import option, a single layer or a range of layers may be selected for import.
- `"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, you have to load the `"dxfio"` plugin 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. The corresponding main menu entry is `"File/Import/Wavefront OBJ"` (if this menu entry is not available, you have to load the `"objio"` plugin 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 and points (e.g. curve on surface) is currently not supported. Furthermore, trimming of freeform curves and surfaces by clamping their knot ranges is not supported (however, since Ayam 1.9, 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. No material and grouping information will be imported. 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, you might want to use a third party tool first to check whether the Wavefront OBJ file is valid at all.

Furthermore, 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) 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.
- `"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.

## 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, you have to load the `"objio"` plugin 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 (ICurve, ConcatNC, ExtrNC)
- NPatch (with trim curves) and objects that may be converted to NPatch objects (BPatch, PatchMesh, Revolve, Sweep, Extrude, Skin, Cap, Gordon, Birail1, Birail2, Text); since Ayam 1.8.3 also Quadrics will be automatically converted to NURBS surfaces and exported
- PolyMesh and objects that may be converted to PolyMesh objects (MetaObj), faces with holes are not supported by the Wavefront OBJ format and will be tesselated to triangles for export automatically
- Box
- Instance, Clone; both will be resolved to normal objects for export as Wavefront OBJ does not support referenced geometry
- Level, CSG operations are not supported and will be written as normal Level objects, transformations will be delegated to the child objects

Since the Wavefront OBJ format does not support separate transformation attributes, all transformation attributes will be used to transform the coordinate values (the control points) of the exported objects. The hierarchy of the Ayam scene will be squashed.

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

The Wavefront OBJ export, currently, ignores all material information. Only the pure geometry information is written to the OBJ file. Since Ayam 1.8.3, however, texture coordinates from primitive variable tags can be exported.

Since Ayam 1.9, UMM/VMM tags are used to trim the knot vectors of exported NURBS objects.

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 file;
- `"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.);
- `"ScaleFactor"` allows to apply a scaling factor to all exported objects;
- `"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.

## 7.10 3DMF (Apple) Import

Using the MFIO plugin you may import scenes 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, you have to load the `"mfio"` plugin 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.

3DMF Primitive | Ayam Object
Polyline | NCurve
Triangle | PolyMesh
TriGrid | PolyMesh
Polygon | PolyMesh
Box | Box
Ellipsoid | Sphere
Cylinder | Cylinder
Cone | Cone
Disk | Disk
Torus | Torus
NURBCurve | NCurve
NURBCurve2D | NCurve
NURBPatch | NPatch
Container | Level

3DMF (Apple) Import Conversion Table

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) 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 you may export scenes 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, you have to load the `"mfio"` plugin 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 saving trim curves in 3DMF 1.0. However, 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 ( ...
                    )
            )
    )

There will always be an enclosing container for a NURBS patch. If the patch is trimmed, after the transformations and attributes of the patch, a `TrimCurves` element will follow (which does not contain the trim curves but is empty). The trim curves follow now as 2D NURBS curves (simple trims) or container objects (trim loops) with 2D NURBS curves until the end of the enclosing container. 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.

### 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"`: The `"ScaleFactor"` option allows to apply a scaling factor to all exported objects.
- `"WriteSelected"`: exports only the selected objects.
- `"WriteCurves"`: If the `"WriteCurves"` 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, you have to load the `"onio"` plugin 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.

Rhino 3DM Primitive | Ayam Object
PolyLineCurve | NCurve
PolyCurve | NCurve
LineCurve | NCurve
ArcCurve | NCurve
CurveOnSurface | NCurve
Mesh | PolyMesh
NurbsCurve | NCurve
NurbsSurface | NPatch
RevSurface | NPatch
SumSurface | NPatch
PlaneSurface | NPatch

3DM (Rhino) Import Conversion Table

### 3DM Import Options

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

- `"ScaleFactor"`: The `"ScaleFactor"` option allows to apply a scaling factor to all imported objects.
- `"Accuracy"`: The `"Accuracy"` import 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 the `"ReadCurves"` import option is switched off, no curves will be imported. This option does not influence the import of trim curves.
- `"ReadLayers"`: By default, all objects from all layers will be imported. Using the `"ReadLayers"` import option, a single layer or a range of layers may be selected for import.
- `"ReadSTrim"`: Another import option is `"ReadSTrim"`. This useful to ignore simple bounding trim loops of NURBS surfaces if they are the only trim loop for that surface. Importing this single bounding trim loop would just make the Ayam scene more complex than needed in many cases. 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, you have to load the `"onio"` plugin using the menu entry `"File/Load Plugin"` first).

### Ayam Object and Properties Support

The export functionality of the onio plugin currently covers export of all boxes, quadrics, NURBS, 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 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. Since Ayam 1.9, a coarse polygonal 3D representation of the 2D trim curves will be created automatically, so that now general trimmed NURBS patches may be exported, albeit with lower quality and bigger file size as would be necessary. Since Ayam 1.9, 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 Ayam 1.8.3, also PolyMesh objects may be exported.

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

for instance, leads to two objects in the Rhino file named `"Arm/MySphere"` and `"Arm/MyCylinder"`.

### 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 the `"WriteCurves"` 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 the `"QuadAsBRep"` 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, you have to load the `"x3dio"` plugin 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, TrimmedNurbsPatchsurface, 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, 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.

Shape elements that contain more than one geometric elements as child objects will be imported as level objects with the child objects using the default transformations and the level object using the current transformation attributes.

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

X3D Primitive | Ayam Object | X3D Primitive | Ayam Object
Geometry3D: |  | CAD: |
Box | Box | QuadSet | PolyMesh
Sphere | Sphere | IndexedQuadSet | PolyMesh
Cylinder | Cylinder | CADLayer | Level
Cone | Cone | CADAssembly | Level
ElevationGrid | PaMesh | CADPart | Level
Extrusion | PolyMesh | CADFace | Level
IndexedFaceSet | PolyMesh | Light: |
IndexedTriangleSet | PolyMesh | DirectionalLight | Light
IndexedTriangleStripSet | PolyMesh | SpotLight | Light
IndexedTriangleFanSet | PolyMesh | PointLight | Light
TriangleSet | PolyMesh |  |
TriangleStripSet | PolyMesh |  |
TriangleFanSet | PolyMesh |  |
IndexedLineSet | NCurve |  |
LineSet | NCurve |  |
Geometry2D: |  |  |
Arc2D | NCircle |  |
ArcClosed2D | NCurve |  |
Circle2D | NCircle |  |
Polyline2D | NCurve |  |
Disk2D | Disk / Hyperboloid |  |
NURBS: |  |  |
NurbsCurve | NCurve |  |
NurbsCurve2D | NCurve |  |
NurbsSurface | NPatch |  |
NurbsPatchsurface | NPatch |  |
TrimmedNurbsPatchsurface | NPatch |  |
NurbsSweptSurface | Sweep |  |
NurbsSwungSurface | Swing |  |

X3D (Web3D) Import Conversion Table

### 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, e.g. for an `"IndexedFaceSet"` element, they will be imported correctly.

Furthermore, since Ayam 1.17, 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. 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 index is not checked, whether it is identical to the vertex coordinate index (and thus no expansion would be necessary).

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) 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.
- `"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, you have to load the `"x3dio"` plugin 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.

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

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.

Object names will be converted to DEF attributes.

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

### 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;
- `"WriteSelected"` exports only the currently selected object(s);
- `"ObeyNoExport"` toggles export of objects with `"NoExport"` tags;
- `"IgnoreHidden"` toggles export of hidden objects;
- `"TessPoMesh"` automatically tesselates all PolyMesh objects to triangles for export;
- `"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 higher level primitives: Revolve as NurbsSwungSurface, Swing as NurbsSwungSurface, Sweep as NurbsSweptSurface, Extrude as NurbsSweptSurface);
- `"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"`, erroneous X3D files may result unless the `"ResolveInstances"` option is switched on;
- `"TopLevelLayers"` arranges for all child objects of top level objects in the Ayam scene to be put in CADLayer nodes;
- `"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.

Next Previous Contents