Okino's DWF-3D and HOOPS HSF 3D File Importer

This import converter reads in files encoded in the Autodesk DWF (3D) file format and in the HOOPS HSF 3D file format. It is one of the most important, problem-solving CAD importers in Okino software for the 2010-2020 era compared to past decades where DXF/DWG was more prevalent for Autodesk CAD conversions.

Please also refer to the corresponding Okino DWF-3D export converter and HOOPS .hsf export converter.

To most people 3D conversion software all looks alike and it is difficult to compare "apples and oranges" when it comes to differentiating one conversion system from another. For such reasons, we will make clear that this is one of the most extensively developed DWF-3D import conversion systems. Having been Autodesk partners and developers since 1992, we realized that one of the most important file formats to implement properly and intelligently would be the "new" DWF-3D format. As important background information, most Autodesk CAD software now implements very good 3D DWF export in products such as AutoCAD, Inventor, Navisworks and Revit. DWF-3D is a much more modern file format for use in data translation compared to the early 1980's conceived native DWG/DXF formats of Autodesk CAD products. DWF-3D allows for complete and clean 3D scene conversion, including a plethora of geometry types, materials, textures, cameras, lights, rendering attributes and more. On the flip side the older DWG/DXF file formats are much more crude, reflecting their original CAD heritage.

As such, we recommend using DWF-3D to convert data coming Autodesk products such as AutoCAD, Revit and Navisworks. For Autodesk Inventor, we recommend our native and direct CAD importer. Okino also actively supports DXF and DWG import + export up to the newest file format versions.

Obtaining the Newest DWF-3D Import/Export Modules

The DWF-3D import/export modules are obtained from the main system architect of Okino software, Robert Lansdale. After you have installed the commercial release of Okino's stand-alone PolyTrans/NuGraf software please email support@okino.com to obtain the current release of these modules.

For demo users, the simplest and most direct method to "evaluate" the DWF-3D modules is to send a source file (in a ZIP archive) to Robert Lansdale and he'll convert it immediately to any destination format or 3D program, without the demo limitations and without you having to download and install the entire demo software package -- this will provide you with a clean example of the conversion process and without every fifth polygon removed as imposed by the demo software.

Documentation for each DWF/HSF Importer Option Panels

Click on any one of the small screen snapshots to jump to the corresponding section of this WEB page:

General	Geometry	Geometry-2	Optimization

Materials	Curves	Selective Loading

Supported Entities and their Conversion

• Polygonal meshes with vertex normals, (u,v) texture coordinates and vertex colors. Both triangle strips and fans are supported.
• Baseline geometry types: shells (boundary only, NULL, collection and edge breaker), meshes, polygons, 3D lines and 3D polylines.
• Curve geometry types: NURBS curves, circular arcs and elliptical arcs.
• Surface geometry types: NURBS surfaces with uv-space trim curves, circles, circular wedge, circular chord, grids and ellipse.
• 2D Text with positioning in 3D space via user settable options. Text encodings of "ISO Latin One", "ISO Latin", "JEC" and "Unicode" are supported. Text region and 3-point regions are supported. Character-level attributes are not supported.
• Extraction of one or all LODs (level of detail).
• Handling of externally referenced files.
• Geometry with per-vertex colors can have the vertex colors automatically migrated and converted into unique material lists. If one or more polygons have different vertex colors per polygon then averaging can be invoked.
• Full instance/object instancing capabilities to reduce the footprint of heavily instanced geometry. Implemented as 'multiply referenced segments' (via 'Include Segment') and 'multiply reference geometry' (via 'geometry reference' or 'repeat object').
• Lights (directional, point and spot), cameras (orthographic and perspective) and their related parameters.
• Very good and complete support for extraction of material definitions.
• Import of global or per-node meta data.
• Extraction of the hierarchy information from a DWF 'content definition' or 'object definition' XML file which is embedded in DWF files exported from Autodesk products.
• Full hierarchy import and post-processing to ensure the most compact number of objects and names in the hierarchy list.
• Images (TKE_Image) embedded in the source file are extracted and assigned to the imported geometry. User settable options also allow the 2D image to be placed 'in 3D space'.
• Automatic bitmap conversion and automated modification of imported shading coefficients.
• Artificial widening of 3D polylines and 3D curves into 'thin polygons', aligned with a user specified plane. This allows polylines and curves, which would otherwise not be renderable, to be rendered with 3D rendering programs.
• Proper accumulation of inherited material attributes. In the HSF/DWF file format there isn't just 'one' material per object, but rather all the various attributes of a material (color, opacity, shininess, etc.) are inherited from different parent levels in the hierarchy. These attributes are accumulated and converted into an Okino material definition according to the following rules:
  • The HSF/DWF ambient, diffuse, specular and emission colors are converted into Okino ambient, diffuse, specular and luminous colors - if any of these are not specified then that corresponding color will be 'locked' to the Okino diffuse color. The Okino shading coefficients will be left as the default (0.3, 0.4, 0.7 respectively).
  • The Transmission attribute is converted into the Okino Opacity parameter. Note that HSF/DWF supports different opacities for the red, green and blue channels - if this case is found, the average opacity of the three is used.
  • The Mirror attribute sets the Okino reflection coefficient of the material's spherical environment map (if used.)
  • The Environment attribute sets the Okino texture map of the material's spherical environment map.
  • The Gloss attribute sets the Okino phong shininess parameter.
  • The Index attribute sets the Okino ray tracing index of refraction surface parameter.
  • Bump mapping is not supported and so the bump mapping attribute is ignored.
  
  
• Texture Map Support:
  • Both TKE_Image textures (textures embedded in the graphics stream) and W3DE_Image textures (textures embedded in the DWF container are supported.)
  • For diffuse textures, texture coordinates must accompany the geometry.
  • Environment textures are expected to use the reflection vector as a parameter source.
  • Clamped and repeated texture tiling is supported but mirrored is not
  • Alpha channel mappings are supported except for zero.
  • Texture value scale, texture coordinate generation and multi-texturing are not supported

How to Export High Quality DWF Files from AutoCAD

One of the core reasons Okino wrote this DWF conversion system was to replace the aging DXF/DWG file formats which are most often associated with AutoCAD. DWF is a much more modern and higher quality file format to use with data translation.

However, one must be aware of how to change the "mesh tessellation quality" parameter inside of AutoCAD software. This parameter controls how finely a BREP solids model will be tessellated into mesh polygons prior to export to the DWF file format. The default value is "2" in AutoCAD, which will most often produce low quality conversions.

To increase the number of polygons during DWF export from AutoCAD:

• Start AutoCAD and load in the model which you wish to export to DWF format.
• Press the F2 key to cause the command window to appear.
• Type "setvar 3DDWFPREC". Press the Enter key. When prompted, enter a value from 2 through 6. Higher values will produce more polygons and hence a better quality DWF file. Depending on the curvature of your AutoCAD model, values of 4 through 6 should suffice.

Unsupported aspects of the DWF-3D and HSF-3D File Format

The DWF-3D file format is actually a "container" that encapsulates several different files inside the .dwf file. The 3D geometry is contained in a HOOPS .hsf file. HOOPS is a very verbose file format for which much of it is not required or used in DWF-3D files. The following is an esoteric list of the unsupported HSF opcodes or features:

• Oblique and stretched cameras and views
• Parametric texture coordinate generation
• Edge colors
• 'Conditions' on references and include segments
• Holes in polygons are not supported since HSF uses the 'even/odd' rule for rendering such holes
• Area lights, cutting planes, clipping regions, texture color channel mappings and texture layouts.
• EUC text encoding (extended Unix Code, mixed 8 & 16-bit values)
• Unsupported texture settings: mirror tiling, gaussian or stochastic texture filtering, texture transform, texture value scale, 2-sided coloring, bump mapping and multi-texturing.
• Animation
• Unsupported HSF opcodes. The following aspects of the imported HSF file are not important to this 3D importer: TKE_Callback, TKE_Clipping_Region, TKE_Conditions, TKE_Edge_Weight, TKE_Face_Pattern, TKE_Font, TKE_Glyph_Definition, TKE_Handedness, TKE_Heuristics, TKE_LOD, TKE_Line_Pattern, TKE_Marker_Size, TKE_Marker_Symbol, TKE_Priority, TKE_Renumber_Key_Global, TKE_Renumber_Key_Local, TKE_Selectability, TKE_Window, TKE_Window_Frame, TKE_Window_Pattern.

General Options Panel

Flip 'Z-Up' to 'Y-Up' coordinate system

Okino software naturally uses a "Y" up coordinate system while HSF/DWF files may use either a Y-Up coordinate system or a Z-up coordinate system. Enabling this option will flip the source Z-up source data to the natural Y-up coordinate system of the main Okino software.

If you find that the data is oriented incorrectly after import then toggle this checkbox.

DWF file optional password

Some DWF files have optional passwords protecting them. If that is the case then enter the password into this type-in box. This password does not apply to HSF files.

Scene scaling factor

This type-in option allows the imported scene to be scaled larger or smaller by a user specified amount.

As examples, enter these values:

1.0 	no scene scaling
1000 	scale 1000 times larger
0.001 	scale 1000 times smaller
4 	scale 4 times larger
0.25	scale 4 times smaller

You can enter a value into the edit box specifying a relative scaling factor and the model will be scaled by this factor. For example, if you enter 2.0, the model will come out twice as large.

Reporting:

Report statistics about the imported file

If this checkbox is check-marked then parsing statistics will be displayed in the message window after the file has been imported, such as:

Polygon meshes = 39
	Polygons            	= 19773
	Vertex coordinates  	= 19890
	Vertex indices      	= 57438
	Vertex normals      	= 16128
	Vertex texture coordinates = 618
	Vertex colors 		= 0
Material definitions 		= 17
Texture definitions (images) 	= 2

Display debugging information

If this checkbox is check-marked then Okino specific debugging information will be displayed in the message window.

Report importer warning messages

If this checkbox is check-marked then warning messages will be displayed during the parsing phase.

Report unsupported features

If this checkbox is check-marked then any unsupported aspects of the source file will be displayed during the parsing phase.

Data Logs

Log file directory

This is the directory where the log files will be stored on disk. Press the "Browse.." button to choose the new directory. If no directory is specified then the log files will appear in the same directory that the original source file came from.

Create an 'object definition' log file

If this checkbox is enabled (check-marked) then a log file detailing the object definition information encountered during a DWF file import will be created (it does not apply to HSF files). This is a technical option used for debugging and software development. It is almost never needed for analysis since the importer outputs warning messages to the "Message Window" if anything out of the ordinary is encountered.

Generate an 'opcode' log file

If this checkbox is enabled (check-marked) then a log file detailing the opcodes encountered during import will be created. This is a technical option used for debugging and software development. It will look similar to this:

1: 0x3B (;)    Comment             ; HSF V11.00 
2: 0x49 (I)    File_Info           00000000
3: 0x5A (Z)    Start_Compression   
4: 0x28 (()    Open_Segment        (ROOT)
5: 0x28 (()    Open_Segment        (Part2)
6: 0x25 (%)    Modelling_Matrix    
7: 0x28 (()    Open_Segment        ()
8: 0x28 (()    Open_Segment        ()

Geometry Options Panel

Level of Detail

HOOPS HSF and Autodesk DWF files have a semi-unique ability to include "level of detail" geometry within their files. Thus, one file may have a very high resolution version of the geometry, and 1 or more lower resolution versions. Each lower resolution version contains much fewer vertices and/or polygons, and hence appears coarser. Some downstream programs use these varying levels of detail to show highly detailed versions of the model when the camera to close to the geometry, and much lower resolution (less complex) versions of the model when the camera is further away.

This importer provides controls over which versions of geometry are imported: all of the versions or just one version (one LOD = one level of detail).

Load all levels-of-detail. LOD to display = #

If this radio button is chosen then all versions of one model (all levels of detail) will be imported. However, all of the LODs will be hidden except for the level specified by the type-in box. By convention, level 0 is the highest quality version of the model (the highest LOD), 1 = the next lowest resolution, 2 = the next-next lowest resolution, etc. You can enter a number up to the highest LOD in the source model.

Load this specific level-of-detail only = #

If this radio button is chosen then only one specific LOD level will be imported, as specified by the type-in number. For example, if this number is set to 2 then only geometry on LOD level # 2 will be imported.

Merge Sibling Geometry

HSF/DWF files use the concept of "segments" extensively. These are like containers or boxes into which items like geometry, material attributes and other key data items are placed within HOOPS databases. While this concept of segments works nicely for displaying and manipulating HOOPS-based databases, they often are not nice when imported into other 3D programs, or via Okino software. While a user may expect a single object after import, HOOPS will instead present the single object as many elements all within one segment.

The following are optimization options which this importer provides as a way to merge together the contents of a "segment" so that much fewer geometry data items are present.

Merge sibling polygon geometry

If this checkbox is enabled (check-marked) then polygon-based geometry in each segment will be merged into a single object where possible. Geometry that has unique metadata or attributes cannot be merged. Enabling this option will often reduce the number of objects in the resulting scene by placing more information in each object.

Merge sibling polyline geometry

If this checkbox is enabled (check-marked) then line-based geometry in each segment will be merged into a single object where possible. Geometry that has unique metadata or attributes cannot be merged. Enabling this option will often reduce the number of objects in the resulting scene by placing more information in each object.

Merge sibling NURBS curves

If this checkbox is enabled (check-marked) then NURBS curve-based geometry in each segment will be merged into a single object where possible. Geometry that has unique metadata or attributes cannot be merged. Enabling this option will often reduce the number of objects in the resulting scene by placing more information in each object.

Emulate 'Include Segments' via 'red folder' instancing

If this checkbox is enabled (check-marked) then the unique Okino master-object + instancing ("Red Folders") method will be used whenever an "Include Segment" is encountered; this method allows one "definition" of an object to be defined in Okino software and 1 or more instances created from it. This option will reduce the number of copies of base geometry in the resulting scene with the caveat that some scenes may be look incorrect. Overall scene memory footprint can be reduced by enabling this option, since multiple instances of the same base geometry will only incur one copy of the base geometry, not multiple copies.

If this option is disabled then the resulting scene will always be correct but will not have use of the red folders mechanism to reduce scene size.

Warning: If materials seem to be applied incorrectly in the resulting scene then this option should be disabled. This can occur if a HSF 'geometry segment' is instanced 2 or more times, and each instance inherits different material properties. HSF allows for specific material properties to be inherited (such as diffuse, specular, ambient colours) rather than entire material definitions as in Okino software. The geometry item from which instances are created must only have one complete material with no sub-material inherited overrides.

Emulate 'geometry markers' via 'Grouping folder' nodes

If this checkbox is enabled (check-marked) then HSF "markers" will be imported as Okino "empty instances" ('Yellow folders' in the Okino stand-alone software's user interface). If this option is enabled, the "Hierarchy Optimizer #1, Hierarchy Optimizer #2" options in the optimization section should be disabled or else these lone grouping nodes will be culled away. If this checkbox is disabled then markers will be merged into a point cloud for each segment.

Ignore polygons which are marked as hidden

If this checkbox is enabled (check-marked) then polygons that are invisible will not be imported. Otherwise, the polygons will be imported and made visible.

Hide 'published edges' (DWF-3D import only)

Autodesk DWF file viewers have 3 main rendering modes: shaded, shaded with edges, and edges only. This allows for lines/curves in the source DWG file which had previously been tagged as 'Published edges' to be selectively hidden or made visible in the DWF file viewer.

Likewise, if this checkbox is enabled then any line/curve geometry in the source file tagged as 'Published edges' will be imported as hidden. If this checkbox is disabled then all geometry will be imported visible.

An example file containing 'Published edges' can easily be made in Okino software by importing a SketchUp 3D model and re-exporting it to DWF-3D with the 'Export lines as published edges'. SketchUp files most often have 3D polygonal geometry as well as outline polylines; the latter will be tagged as 'Published edges' when re-exported in this suggested manner.

ISO-Latin language code page

This dropdown box allows you to select the code page used whenever ISO-Latin text is found. Since ISO-Latin has many different code pages corresponding to the different sets of languages, you can select which code page you believe the file was created in.

A 'code page' is used to map from the 8-bit characters found in the source file to the wide-string characters used internally within Okino software.

The following code pages are supported:

ANSI
Machine default
ISO-8859-1 (Latin 1)
ISO-8859-2 (Latin 2)
ISO-8859-3 (Latin 3)
ISO-8859-4 (Baltic)
ISO-8859-5 (Cyrillic)
ISO-8859-6 (Arabic)
ISO-8859-7 (Greek)
ISO-8859-8 (Hebrew)
ISO-8859-9 (Turkish)
ISO-8859-15 (Latin 9)

Geometry-2 Options Panel

'Infinite Geometry' Emulation

The HOOPS geometry sub-system allows for the creation of "infinite geometry" which has no geometric bounds. Unfortunately there exists few other 3D file formats or programs which allow for such geometry definition. These options allow such "infinite geometry" to be emulated by equivalent finite and reproducible geometry after the data has been imported.

Infinite polyline length

This type-in number sets the absolute length of 'infinite length' lines in object-space coordinates.

Infinite grid width repetition

This type-in number defines how many repeats (in the 'width' direction) are made to define an 'infinite quadrilateral grid'.

Quadrilateral grids in HSF are specified using four points to form a base. The base is then repeated outwards some width and height number of times. The grid can be infinite in either direction. This option allows you to specify a fixed number of repetitions of the width to approximate the infinite width. Negative numbers indicate that the grid should repeat in both width directions. This value cannot be zero.

Infinite grid height repetition

This type-in number defines how many repeats (in the 'height' direction) are made to define an 'infinite grid'. Negative values will repeat the grid in both directions of height

This option allows you to specify a fixed number of repetitions of the height to approximate the infinite height. Negative numbers indicate that the grid should repeat in both 'height' directions. This value cannot be zero.

Infinite grid radius repetition

This type-in number defines how many repeats are made for a 'radial' grid. The radius of the grid is repeated by this type-in value, which must be positive. Radial grids are specified by a wedge. This option allows you to specify a fixed number of repetitions outwards to approximate an infinite grid.

Add Artificial 'Width' to 3D Polylines & Curves

This is an unusual pre-processing operation that can be used to turn 3D polylines and 3D curves (which have no area) into thinly widened polygons (which do have an area) that can be re-exported to programs which only accept polygonal data, or can only render polygonal data.

Why would you want to do this? Some destination programs and file formats for the DWF/HSF source data cannot accept 3D polylines and/or 3D curves, but only polygons; hence the polylines/curves need to be converted into an approximation using polygons (which are more universal). In addition, most 3D programs cannot raytrace or scanline render 3D polylines or curves since they have no area, and thus a polygonal approximation to them is needed instead. As an example, you could use this option to import a purely flat, 2D drafting diagram made up out of polylines/curves, and allow it to be rendered in a 3D rendering program. There is an equivalent version of this option on the Okino DWF/DWG importer.

During the processing of the HSF/DWF polyline/curve data, the geometry is approximated by a number of very narrow polygons. From a distance, the polygonal data will appear to look like thin polylines or curves. The new polygons will all lay in one specific 3D plane, as defined by the combo box below. The most import parameter to set is the "Width" which will define how wide the new approximated lines will be.

Widen Polylines

If this checkbox is enabled (check-marked) then 3D polylines will be widened into polygons with a width defined by the "Width" type-in value.

Widen Curves

If this checkbox is enabled (check-marked) then 3D curves will be widened into polygons with a width defined by the "Width" type-in value.

Width

This type-in value sets the width in world-space coordinates of the lines generated when either the "Widen Polylines" or "Widen Curves" options are set.

Curve tessellation (slider)

This slider determines how smoothly the curves will be approximated into linear line segments before they are in turn converted into thin polygons. This slider sets the curve tolerance to be a percentage of the curve's bounding box. Lower values (to the left of the slider) will create smoother approximations to the curve, while higher values will create coarser approximations. The lower the value goes, the more polygons will be created, so don't set the slider arbitrarily too low.

Plane to place the widened geometry

In order to give width to the polylines and curves, the "width" needs to be defined relative to some two dimensional plane. The final widened polylines/curves will lay flat in this desired plane. This combo box allows you to specify one of 3 planes: XY, YZ, XZ.

Placement of Text & Images in "3D Space"

The HOOPS HSF files format (and DWF) allows for the special case of 2D text and 2D images to be placed "in the flat plane of the screen". In other words, regardless of the changes to the orientation of the 3D camera which is viewing the 3D scene, this 2D text and/or 2D images will remain static on your monitor screen when viewed by a HSF file viewer. This can be used to create 2D overlays that remain static regardless of how the 3D scene is manipulated or viewed.

Unfortunately this mode of operation cannot be recreated outside of a true HSF file viewer, as it is specific to the HSF file format and HSF viewers. This importer will attempt to import and simulate this custom model of HSF operation.

The following options will allow the 2D text and/or images to be imported and placed on a specific oriented 2D plane in space. Scaling values will allow you to control the size of the imported text/images as placed on this plane.

Plane to place text & images:

This combo box determines which plane, and orientation, that the imported 2D text and/or images will be placed.

'2D Window Units' to 3D scale

'2D Subscreen Units' to 3D scale

'2D Pixel Units' to 3D scale

'2D Point Units' to 3D scale

HSF allows the 2D text and/or images to be defined in different coordinate units: 'window relative', 'sub-screen relative', pixels or points. These type-in values define 4 scaling factors that map from these 4 coordinate units into the uniform local coordinates of your selected 2D projection plane. In other words, these values scale from window/sub-screen/pixel/point units of measure into the one, uniform 3D coordinate system into which the 2D text/images are to be placed.

These scale factors specify how many 3D object-units each unit of the variable specific type is worth. For example, if you wanted 12 pixels to become 2 object-space units high on the destination 2D plane then you would set the '2D Pixel Units' to 3D scale value to 2.0 / 12.

Place images in 3D space (HSF TK_Image only)

The HSF file format allows for the unique ability to have 2D raster images be used directly as geometry, or inversely in the more common use as texture map images. Since images are inherently two dimensional, additional effort is required to orient them in three dimensions when used as geometry.

If this checkbox is disabled (uncheck-marked) then any 2D images found in the HSF file will only be used for texture mapping purposes. This is the default.

If this checkbox is enabled (check-marked) then any 2D images found in the HSF file will be place into the 3D scene as "flat geometry" items, oriented and scaled onto the same 3D plane as mentioned above. In other words, the 2D images will not be used for texture mapping but instead will be imported and placed flat to the plane selected by the combo box above, and scaled on that plane to be a size defined by the 4 scaling values listed above.

Optimization Options Panel

Hierarchy Optimizer # 1, Hierarchy Optimizer # 2

These options provide methods to remove redundant hierarchy nodes ('NULLs', or grouping folders) from the imported file. Optimizer #1 removes runs of empty folders, as well as folders with no children. Optimizer #2 is simpler, deleting empty folders which only have 1 geometry object in them. These options can also be enabled via the "Optimize hierarchy after completion" checkbox found on the options dialog box of the "Compress & optimize number of objects" option (see below).

Compress & optimize number of objects

This checkbox enables one of the most important and critical scene processing functions in all of Okino software. It is an integral and core part of any Okino CAD importer, and it has been added to the HSF/DWF importer for added benefits.

The primary purpose of this function is to walk the imported geometry hierarchy and compress together all objects that are parented under a single folder into a one new object. For example, if you import a HSF/DWF file and find that 200 polygonal objects are grouped under one folder, then enabling this option will cause all such occurrences to collapse the children geometry of each grouping folder into one object.

The documentation for this option can be viewed by pressing the "Options" button and then the "Help" button on the optimizer's dialog box.

Convert mesh vertex colors into explicit material references

This is an interesting vertex colors optimization. As background, there are some HSF/DWF files which have no materials assigned to the geometry, but rather all color comes from explicit RGB colors assigned to each vertex of the polygonal geometry. By itself this is acceptable, but most 3D file formats and 3D programs do not use vertex colors for geometry coloring, but rather assigned materials.

If this optimization is enabled then the importer will remove the RGB vertex colors from the mesh geometry and replace them with pointers to equivalent material definitions. The RGB vertex color values will be placed in the material definitions as the "diffuse" material color.

Maximum unique colors to convert per mesh = #

This is a threshold value. If the number of vertex colors on a mesh is greater than this type-in value, then no optimization will be performed for that one mesh object. In other words, the vertex colors will remain attached to the geometry and they will not be replaced by equivalent material assignments.

As an example of why this might be useful, consider a case where a mesh geometry item has 32000 unique vertex colors assigned to it. In this case we would probably not want to create 32000 material definitions, as that would blow up many downstream 3D rendering and animation systems (often, 256 materials is a good upper limit for many 3D programs).

Average together vertex colors of multi-colored polygons

The only drawback of this optimization method is that the newly assigned material is on a per-polygon basis, not a per-vertex basis. Hence, if a polygon has different RGB vertex colors on some or all of its vertices, then it will not be possible to replace all of them with unique materials.

If this checkbox is enabled then all the vertex colors assigned to one polygon will first be averaged together into one unique color. That one unique color will then be converted and mapped over to a new and unique material. The new material will be assigned to that one polygon. Hence, this is our solution of solving the 'too many vertex colors on one polygon' problem. Note that many new material definitions may be created by enabling this option.

Compute averaged vertex normals if none found in the source file.

Vertex normals are vectors contained at each polygon vertex that are used to make the polygon mesh "appear to be smooth" in a 3D rendering program. If such vertex normals do not exist on a polygon mesh object then it will render 'faceted' and not smooth.

If this checkbox is enabled then new vertex normals will be computed for a polygon if it does not have any vertex normals already. The smoothing criterion is based on the angle between abutting polygons; common smoothed vertex normals will be computed if the angle between their geometric surfaces normals is less than the angle specified on the dialog box (which defaults to 45 degrees).

Optimize (weld) mesh coordinate lists

These options allow vertex XYZ oordinates, vertex normals, vertex uv texture coordinates and vertex RGB colors to be 'welded' together, or in other words, duplicate entries removed from their respective lists based on a small tolerance value.

Typically the "Weld nearby vertices" option is used most often from this list of vertex optimizers. In particular, it is important to enable it if you also have the 'Compute averaged vertex normals" option enabled (see above), as it may not work unless all the vertices of a mesh are first welded together (made coincident and shared).

Weld nearby vertices

If this checkbox is enabled (check-marked) then the vertex welding operation will be applied to all polygon vertices once the HSF/DWF file has been read into memory and the objects created. Vertex welding collapses adjacent vertices which are within a distance less than or equal to the threshold value specified on the dialog box. Note that welding of vertices can only occur within a single object and not between different objects.

'Max distance' Type-In

If the distance between two vertices is less than or equal to this number, and the "Weld nearby vertices" checkbox is check-marked (enabled) then the two vertices will be collapsed (welded) into one.

Remove duplicate vertex normals. Max diff = #

This is the same as the 'Weld nearby vertices' function except that it combines redundant vertex normals that are within a certain numerical threshold of each other.

Remove duplicate texture coords. Max diff = #

This is the same as the 'Weld nearby vertices' function except that it combines redundant 2D vertex uv texture coordinates that are within a certain numerical threshold of each other.

Remove duplicate vertex colors. Max diff = #

This is the same as the 'Weld nearby vertices' function except that it combines redundant vertex RGB colors that are within a certain numerical threshold of each other.

Material Options Panel

Strip off File Paths from Bitmap References

If this option is enabled then absolute file paths will be stripped off from the bitmap references. If disabled, file paths will remain unmodified. For example, if this option is enabled and the reference to a bitmap texture image is "c:\images\my_image.tif", then the file reference will be imported into the material definition as "my_image.tif".

Shading Coefficient Modifications

See the end of this help file for a longer explanation of these combo boxes. In general, these combo boxes allow the key material attributes to be tweaked during import. This might be necessary, for example, if the imported objects appear too ambient, or too luminous.

Extract embedded texture images from source file

The HSF/DWF file format allows texture maps (raster images) to be embedded directly inside the files. This dialog box describes how those raster images will be extracted and converted back to TIFF files on disk.

If this option is enabled then the texture maps embedded in the HSF/DWF file will be extracted to disk as TIFF images.

Confirm overwrites when saving out texture images

If this option is enabled then you will be prompted whether an existing TIFF file on disk should be overwritten.

Save embedded texture images to this directory

These radio button options define where the extracted TIFF texture maps will be written to disk.

Directory where this program was executed from

The extracted TIFF images will be saved in the directory where this program began execution (which is usually the same as where this program is located on disk). This is not a preferable option since this directory will eventually become cluttered with TIFF images extracted from HSF/DWF files.

Directory where source input files are located

The extracted TIFF images will be saved in the same directory where the HSF/DWF input file was read from. This is the default but in general you should store the TIFF files in a common textures directory.

Specific

The extracted TIFF images will be saved in the directory indicated by the static edit box. If no directory is shown, or you want to change the current directory, then the Browse button can be pressed to select the desired destination directory.

'NURBS Curves' Import Options Panel

This following options control the import of NURBS curves.

Display NURBS Curve Control Point Locations on UI

If this checkbox is check-marked then the control point (CV) locations used by any 3D independent NURBS will be displayed. This option is only applicable when viewing imported NURBS curves within the Okino stand-alone software.

Specify closed NURBS curves as being renderable

If a NURBS curve forms a closed loop, and this option is enabled, then those curves will be flagged as being "renderable". This only has significance to the Okino stand-alone PolyTrans or NuGraf software in which case such "renderable" curves can be scanline or ray traced rendered as a 3D surface and not just a 3D curve.

Also, if the curve loop is set as renderable, then it can be (optionally) converted into a trimmed NURBS 3D surface when being re-exported to other 3D programs, such as Maya or 3ds Max.

Enable NURBS curve cleansing during import

If this option is enabled then the NURBS curves will be "cleansed" (multiple knots removed as best can be done, and the knot vector is clamped). This option is enabled by default.

'Selective Loading' Options Panel

The following checkboxes allow all or only some parts of the DWF/HSF file to be loaded.

Meshes (shells, polygons, polyCylinders, meshes)

If this checkbox is enabled (check-marked) then all polygon mesh geometry will be imported from the source file (triangle or polygon lists). This affects the following HSF opcodes: TKE_Mesh, TKE_Shell, TKE_Polygon, TKE_PolyCylinder, TKE_Cylinder and TKE_Grid (Quadrilateral)

You can also selectively choose specific parts of the mesh to load:

Vertex Normals

Load in vertex normals. This affects the HSF opcodes: TKE_Mesh and TKE_Shell.

Vertex Texture uv's

Load in texture uv vertex coordinates. This affects the HSF opcodes: TKE_Mesh and TKE_Shell.

Vertex Colors

Load in vertex colors. This affects the HSF opcodes: TKE_Mesh, TKE_Shell and TKE_PolyCylinder.

3D line geometry (lines, polyLines, polyPolyLines)

If this checkbox is enabled (check-marked) then all line geometry will be imported from the source file. If disabled then all line geometry will be ignored. This affects the following HSF opcodes: TKE_Line, TKE_Polyline and TKE_PolyPolyLine.

Cameras (TKE_Camera and/or TKE_View)

If this option is enabled (check-marked) then 3D cameras will be imported from the source file. This affects the following HSF opcodes: TKE_View and TKE_Camera

Lights

If this option is enabled (check-marked) then point, directional and spot light sources will be imported. This affects the following HSF opcodes: TKE_Local_Light, TKE_Distant_Light and TKE_Spot_Light.

Marker geometry

If this option is enabled (check-marked) then HSF 'markers' will be imported (as grouping folders) otherwise they will be ignored. This affects the following HSF opcode: TKE_Marker.

Materials

If this option is enabled (check-marked) then all material information will be imported and applied to geometry. If this option is disabled then no geometry will have any material information.

NOTE: Vertex colors are independent of this option and their import can be disabled using the "Vertex colors" checkbox.

This affects the following HSF opcodes: TKE_Image, W3DE_Image, TKE_Texture, TKE_Color, TKE_Color_By_Value, TKE_Color_RGB, TKE_Color_By_Index and TKE_Color_By_FIndex.

2D Material Textures

If this option is enabled (check-marked) then all textures and images will be processed normally. If this option is disabled then all textures and images will be ignored; all material attributes that refer to textures will be ignored. This affects the following HSF opcodes: TKE_Image, W3DE_Image, TKE_Texture and TKE_Color.

Meta Data

If this option is enabled (check-marked) then all metadata will be imported, otherwise it will be ignored. This will affect both the object definitions found in a DWF container and the metadata found in the following opcodes: TKE_User_Index, TKE_User_Value, TKE_User_Options, TKE_Unicode_Options and TKE_User_Data.

NOTE: The metadata found in the DWF container may be used by this importer for naming Okino grouping folders ('yellow folders'). If this option is not selected, the grouping folders corresponding to HSF segments will use the segment names found in the HSF data and will not use the replacement names that may be found in the DWF container.

Curves (elliptical + circular arcs, NURBS curves)

If this checkbox is enabled (check-marked) then all 3D curve geometry will be imported from the source file. If disabled then all 3D curve geometry will be ignored. This affects the following HSF opcodes: TKE_NURBS_Curve, TKE_Elliptical_Arc and TKE_Circular_Arc.

NURBS surfaces

(NURBS surface, circle, ellipse, circular wedge, circular chord, radial grid) If this option is enabled (check-marked) then NURBS surfaces will be imported from the source file. If disabled then all NURBS surfaces will be ignored. This affects the following HSF opcodes: TKE_NURBS_Surface, TKE_Circle, TKE_Circular_Wedge, TKE_Circular_Chord, TKE_Ellipse and TKE_Grid (Radial).

NURBS Trim Curves

If this option is enabled (check-marked) then NURBS trim curves associated with NURBS surfaces will be imported from the source file. If disabled, then all NURBS trim curves will be ignored (the NURBS Surface will be still be imported according to the above option. This affects the HSF opcode TKE_NURBS_Surface.

Text

If this checkbox is enabled (check-marked) then 2D text geometry will be imported from the source file, otherwise it will be ignored and not imported. Text encodings of "ISO Latin One", "ISO Latin", "JEC" and "Unicode" are supported. Text region and 3-point regions are supported. Character-level attributes are not supported. This affects the HSF opcodes: TKE_Text and TKE_Text_With_Encoding.

Shading Parameter Modification Combo Boxes

These combo boxes provide hands-on control over how imported material shading parameters should be modified so that the imported model can be rendered nicely in a photo-realistic rendering program. All too often the imported model appears "too diffuse" resulting in rendered images that are washed out or with no gradual shading effects visible. The two combo boxes and the single numeric type-in box provide you good control over the diffuse, specular and luminous shading coefficients imported into PolyTrans/NuGraf, as well as the opacity of the material and Phong shininess value.

The first drop-down combo box selects which of these shading parameters you want to modify. Each shading coefficient has its own operation which can be selected (the second combo box) and an optional numeric type-in value (the third data entry text input). The following describes the various shading parameters that can be controlled:

Diffuse Coefficient: This controls the amount of color reflected from an object based on the direct light shining on it. A good default value is 0.4 and ideally ranges from 0.0 to 1.0. Some programs have a diffuse shading coefficient parameter (NuGraf/PolyTrans, etc) while others do not (3ds Max). If an export file format does not support a diffuse shading coefficient then this value will be multiplied into the diffuse shading color itself.

Specular Coefficient: This controls the intensity of the highlight color on an object. A good default value is 0.7 and ideally ranges from 0.0 to 5.0. If an export file format does not support a specular shading coefficient then this value will be multiplied into the specular shading color itself.

Luminous Coefficient: This controls how much color is added directly to an object, irrespective of any light which shines on it (the higher the value, the more the object will appear to glow). In general you should keep this value at 0. If an export file format does not support a luminous shading coefficient then this value will be multiplied into the luminous shading color itself.

Opacity: This is the inverse of transparency. 0.0 will make the object fully transparent, while at 1.0 the object will be fully opaque.

Phong Shininess: This controls the width of the specular highlight seen on an object. An ideal range is 6 (very wide) to 300 (very narrow). The default is 32.

For each material shading parameter, several actions can be performed on it during the import process:

Do Not Import: The shading parameter is not imported at all. No value is imported nor sent to PolyTrans/NuGraf. Thus, the default material shading parameter value (as set inside PolyTrans/NuGraf) will be used instead.

Import Unchanged: The shading parameter is imported as is, with no change.

Set and Use Default: The shading parameter is set to some "good" default value (as determined by the import converter). This default value will be shown in the type-in box.

Set to Specific Value: The imported shading parameter will be overridden with the user specified value of the numeric type-in box.

Import and Crop by: The shading parameter is imported and will remain unchanged if it is less than the numeric type-in value shown on the dialog box. If it is greater, then the imported value will be clamped to be no greater than the numeric type-in value. This is a good operation, for example, if you do not wish for the ambient shading coefficient to be greater than 0.3.

Import and Scale by: The shading parameter is imported and multiplied by the numeric type-in value shown on the dialog box

Normalize Color and Coefficient: This option only applies for the ambient, diffuse, specular and luminous shading coefficients and their respective RGB colors. This option is a hybrid approach which tries to automatically 'guess' at a proper shading coefficient value given the raw (and corresponding) color imported from the file. As mentioned, the shading coefficient is needed to create nice looking (nicely shaded) images in a photo-realistic rendering program. If this option is chosen, then the specific shading coefficient will be derived directly from the relative intensity of the imported color which corresponds to this shading coefficient (diffuse color for diffuse shading coefficient etc.). For example, if the imported diffuse color is (0.4, 0, 0), which is 40% of full-bright red, then the diffuse shading coefficient will be set to 0.4 and the diffuse color will be modified to be (1, 0, 0). When the new color (1,0,0) and the new shading coefficient (0.4) are multiplied together, it results in the original color imported from the file (0.4, 0, 0). In general you may wish to use the "Set and Use Default" option to get good rendered results.