Ayam: Import and Export

Next Previous Contents

## 7. Import and Export

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

## 7.1 Mops Import

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 NCurveAttrib, and NPatchAttrib for more information about tolerance and display mode) 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.2 RenderMan Interface Bytestream (RIB) Import

Using the RRIB (Read RIB) plugin you may import RenderMan Interface Bytestreams 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).

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 other calls to the RenderMan Interface not that useful for a RIB import like e.g. RiMakeTexture. Unsupported geometric primitives and other calls to the RenderMan Interface are silently ignored.

The RIB import may be controlled via different options:

- `"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.
- `"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.
- `"ErrorLevel"`, this option controls how many error messages should be printed to the Ayam console while reading the RIB. Available values are: `"Silence"` no output except for severe errors, `"Errors"` all error messages should be printed, `"Warnings"`, all error and warning messages should be printed, and finally `"All"` all messages, even informative, should be printed. 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).

Note that for NURBS patches and bicubic patch meshes, points of type "P" will be promoted to "Pw". Trimming of NURBS patches by clamping the 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). Furthermore, objects of type (general) polygon and polygon mesh will 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.

## 7.3 Wavefront OBJ Import

Since Ayam 1.8.3 a Wavefront OBJ (version 3.0) import facility is available. The corresponding main menu entry is `"File/Import/Wavefront OBJ"`.

Wavefront OBJ import supports reading of polygonal faces with vertex normals and texture coordinates (read as primitive variable tags) and freeform curves and surfaces (NURBS) with trim curves and with texture coordinates (read as primitive variable tags).

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). No material and grouping information will be imported. Unsupported statements will be silently ignored.

The following options further control the 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.
- `"MergePVTags"` controls, whether the PV tags of PolyMesh objects should be merged as well if they are subject to automatic merging (see above).
- `"OmitCurves"` if this is enabled, no freeform curves will be imported. This option does not influence reading of 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. 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.
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates.
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

Wavefront OBJ import expects the file to be syntactically correct. It is not very good in detecting and reporting errors. If the import fails, use third party tools first (e.g. a demo version of Okino Graphics PolyTrans(R)), to check whether the Wavefront OBJ file is valid at all.

## 7.4 Wavefront OBJ Export

Since Ayam 1.7, it is possible to export scenes or objects to the Wavefront OBJ format (version 3.0). The corresponding main menu entry is `"File/Export/Wavefront OBJ"`. The Wavefront export currently supports the following primitives:

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

The following parameters, additionally, control the Wavefront OBJ export:

- `"FileName"` is the filename of the Wavefront OBJ file;
- `"Selected"` exports only the currently selected object(s);
- `"TessPoMesh"` automatically tesselates all PolyMesh objects to triangles for export;
- `"OmitCurves"` omits all NURBS curves and NURBS curve providing objects from the exported file (This option does not influence the export of trim curves.);
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates, and
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

## 7.5 3DMF (Apple) Import

Using the MFIO plugin you may import scenes from the 3DMF format (version 1.0 only!) from 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).

Import supports the following primitives:

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

The following transformations are supported:

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

## 7.6 3DMF (Apple) Export

Using the MFIO plugin you may export scenes to the 3DMF format (version 1.0 only!) from 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 export supports the following primitives:

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

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 red 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.

## 7.7 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 import functionality of the onio plugin currently covers import of all NURBS and BRep objects and objects that may be converted to NURBS using the OpenNURBS toolkit (those 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 Mesh objects will be imported to PolyMesh objects, texture coordinates will be read and appropriate PV tags will be created.

The import process is controlled by the following options:

- `"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.
- `"IgnoreFirstTrim"`: Another import option is `"IgnoreFirstTrim"`, this is useful if the first bounding trim loop of NURBS surfaces should be ignored. This trim loop is often not needed, because it encloses the whole surface that is not trimmed further in many cases. Importing this trim loop will often just make the Ayam scene more complex than needed.
- `"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. 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.
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates, and
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

## 7.8 3DM (Rhino) Export

Since version 1.8.2 Ayam contains a plugin named onio that may export 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).

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.8.3, also PolyMesh objects may be exported. Since Ayam 1.9, UMM/VMM tags are used to trim the knot vectors of exported NURBS objects.

The export process is controlled by the following options:

- `"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 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 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 objects in the scene to be exported should be interpreted as layers. If this option is enabled, objects that are not in one of those levels will be written to the default layer.
- `"STagName"` controls the name of the PV tag to be used for the s component of the texture coordinates, and
- `"TTagName"` controls the name of the PV tag to be used for the t component of the texture coordinates.

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

Next Previous Contents