This import converter reads in raw FACT files from the Electric Image
animation system. FACT files are also a common format to move scene data in
and out of the Form/Z modeling program. This FACT importer (and its corresponding
FACT export converter) have been under constant development for a period of
3+ years at Okino - it has been one of the harder converters to implement
properly because of the little 'hands on' documentation available for the
FACT file format and due to its differing/limited nature in handling 3D data and
texture mapping compared to other 3D file formats (we greatfully acknowledge
the raw file format information provided to Okino by Matt Hoffman of Electric Image).
NOTE: If the FACT file will not load, see the Skip Odd Bytes at End of Data Chunks and/or Byte Encoding Format parsing options are the end of this help file.
The following are some of the features of this import converter:
All geometry is read in including the simple/complex geometry sub-data types, vertex normals, uv texture coordinates, vertex colors and tangent vectors,
The complex hierarchy of the FACT file, including the preservation of linkage information and child/parent transformation information. Pivot points are properly derived from the linkage information.
Material definitions (ambient/diffuse/specular colors, index of refraction, shading model, Phong highlight size and face opacity).
Texture mapping information (filename, u/v scale, crop window information).
All Electric Image texture projection methods (flat, cubic, spherical and cubical) are converted to equivalent NuGraf/PolyTrans texture projection methods.
Converter Limitations
Electric Image project files cannot be imported. This is because the project file format is not documented.
Animation data cannot be imported. This is because the animation data is contained within the Electric Image project files.
Only one texture map per object is accommodated even though Electric Image allows unlimited textures to be layered upon a single object.
Electric Image Effectors are inserted into the object hierarchy graph as Yellow grouping folders.
As with Electric Image, the pivot points are placed at the center of object rotation.
Electric Image allows an object to inherit attributes such as position, rotation, and scale from its parent. Files that have these inheritance attributes will be imported properly. However, this inheritance information will no longer be present within Polytrans or NuGraf.
Certain types of texture modulations can't be imported. For example clipping, displacement, glows, transmissions and edge maps are not supported.
Currently only the default rotation order (XYZ) is supported by the importer.
Some complex material properties are not handled, such as:
Edge attributes (edge transparency, edge maps)
Reflection Color
Glow (although luminance is supported)
Silhouettes
Dissolves
Dialog Box Options
Geometry Processing Options
These options control how the imported geometry data is processed before it is sent to the NuGraf/PolyTrans internal database.
Compute Normals using Assigned Smoothing Angles
If this checkbox is check-marked then vertex normals will automatically be computed if an objects smooth shading flag is enabled inside the FACT file. The smoothing will be computed based on a 45 degrees smoothing angle. If this option is disabled, or the smooth shading flag is disabled within the FACT file, then the vertex normals will be imported directly from the FACT file (if they exist).
Create Unique Set of Material Definitions
If this checkbox is check-marked then only a unique set of material definitions will be created based on the imported materials from the FACT file. If disabled, a material definition will be created for every material specified in the FACT file.
Mirror (Flip) Imported Objects Along Z Axis
If this checkbox is check-marked then the imported geometry will be mirrored in the XY plane (each Z coordinate will be replaced with -Z).
Switch Coordinate System so that Y is Up
If this checkbox is check-marked then the imported geometry will be rotated so that the Y axis points upward instead of the Z axis.
Remove Double Sided Polygons
While this option is not really needed for FACT files, it allows double sided polygons to be removed. Double sided polygons are actually 2 physical polygons that occupy the same area in space; each polygon has a reversed orientation. If this option is enabled then one of these double sided polygons are removed. This operation can be very slow to perform.
Shading Coefficient Modifications
See below 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.
Selecting Loading
These options allow specific portions of the FACT file to be imported.
Vertex Normals
If checkmarked, vertex normals will be imported for each object. Some FACT files contain vertex normals which are used to make the imported object appear smooth when shaded.
Vertex Colors
If checkmarked, vertex colors will be imported for each object. However, not all export file formats can handle vertex colors. This option is disabled by default because the objects normally receive their color from the material definitions.
Color Texture Coordinates
If checkmarked, vertex uv texture coordinates will be imported for each object. These texture coordinates (if provided) are necessary in order for 2d bitmap textures to be applied to objects. Normally the uv texture coordinates are derived from the FACT texture projections (see below) instead of from these explicit object texture coordinates.
Vertex Tangent Vectors
If checkmarked, UV tangent vectors will be imported for each object. These tangent vectors are necessary when bump map texture mapping is applied to the object. The tangent vectors define the plane perpendicular to the vertex normals.
Texture Projections
If checkmarked, the Electric Image texture projections will be imported. These projections are used inside Electric Image to position a texture map on an object. Please note that if an object has a texture projection assigned to it then the projection will override any uv texture coordinates imported from the FACT file for that object.
Object Hierarchy
If checkmarked, the object hierarchy from the FACT file will be recreated. FACT files have some of the most complex transformation hierarchies of any 3D file format (mostly due to their complex articulated animation system).
Statistics and Warning Messages
Report Statistics About the Geometry File
If this checkbox is check-marked then parsing statistics will be displayed in the message window after the FACT file has been imported.
Print Warning Messages
If this checkbox is check-marked then warning messages from the FACT file parser will be printed out to the message window.
Output Parsing Information to File debugfct.txt
If this checkbox is check-marked then the contents of the FACT binary file will be verbosely described and output to the file debugfct.txt.
FACT File Parsing Options
These options control how the raw parsing of the binary FACT file is to be handled.
Skip Odd Bytes at End of Data Chunks
It is typical of files written on the Apple Macintosh platform that all data chunks have an even length (ie: a size of 2, 4, 6, etc). However, we have encountered some FACT files which have chunk sizes which are non-even (ie: a size of 1, 3, 5, etc). If you find that a FACT file will not load, try enabling this checkbox option - it will allow chunks with non-even sizes to be imported.
Byte Encoding Format
Normally all FACT files are written using the Big Endian byte ordering method (since Big Endian mode is used by Macintosh machines). This method determines how 16-bit, 24-bit and 32-bit numbers are stored inside the FACT file. However, if a FACT file does not load at all then you may want to try the Little Endian mode (in case the file was incorrectly written by a source 3D software package).
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 ambient" or "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 ambient, diffuse, specular, luminous and reflection shading coefficients imported into PolyTrans/NuGraf, as well as the opacity of the material, its index of refraction (IOR) 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:
Ambient Coefficient: This controls the amount of color reflected from an object based on the ambient light in a scene. A good default value is 0.1 through to 0.3 and ideally ranges from 0.0 to 1.0. Some programs have an ambient shading coefficient parameter (NuGraf/PolyTrans, Electric Image, etc) while others do not (3D Studio). If an export file format does not support an ambient shading coefficient then this value will be multiplied into the ambient shading color itself.
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, Electric Image, etc) while others do not (3D Studio). 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.
Reflection Coefficient: This controls the ray trace reflectivity of an object. If set to 1.0 then the object will be 100% reflective and if set to 0.0 then the object will not be reflective at all.
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.
Index of Refraction (IOR): This is the ray traced index of refraction of an object. If the value is greater than 1.0 then a ray will refract as it passes from one material to another (as per Snells law), each of different IORs. Ideal ranges are 1.0 through to 3.0.
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.
Supported FACT Import and Export Chunks
The following is a succinct list of FACT file format chunks that are supported in the FACT importer and exporter.
TVER (export) - The use of the TVER chunk is undocumented:
typedef struct {
ulong translateVersion; /* Translation library version number */
ulong translateDate; /* Date of the last model translation */
} TVER, *TVERPtr;
Through trial and error we have noticed that if the chunk is not
present, in the FHDR chunk EI does something strange: it actually
converts the FACT file into another FACT file and then presumably
loads the converted file. This delays import times. However, if a
dummy TVER chunk is loaded there is no problem loading the file and
no conversion takes place.
GINF (import/export) - The GINF chunk stores general information
about an object. It stores several matrices that describe the
objects position. It also stores information about how many child
objects the current object has for determining hierarchy.
Bounding boxes are also stored in GINF. EI uses this bounding box
instead of recalculating one so it is important that the exporter
exports this.
GSTR (import/export) - The GSTR chunk contains information about
an objects orientation. It has information on the objects
position, rotation etc.
GLNK (import/export) - The GLNK chunk contains information on the
way an object is connected to other objects. It has information
on what traits are inherited from a parent object/effector. It
also contains information on an objects position from its parent.
GATR (import/export) - The GATR chunk contains information on the
surface attributes for an object. Currently the exporter exports
the following surface attributes.
/* Specular reflection color, alpha=gloss factor (255=no gloss; 0=100% gloss) */
/* Surface color (overrides element color when override color flag is set) */
/* Ambient reflection color */
/* Specular reflection color, alpha=gloss factor (255=no gloss; 0=100% gloss) */
/* Self illumination components, alpha=shade factor */
/* Diffuse reflection color */
/* Transparency components, alpha=opacity (255=solid; 0=invisible) */
Other attributes in the chunk are left as default. The material
information is very limited in the GATR chunk. Most of the
options pertaining to materials do not appear in this chunk. For
this reason the GATR chunk should always be followed by a GMAT
form. However, in files exported from older versions of EI this
may not be the case.
GMAT (import/export) - The GMAT form is used in EI's newer
material system. The GMAT contains much more information than
the GATR chunk. When this form is available it overrides the
material information found in the GATR chunk. The GMAT form
actually contains a large number of sub-chunks. Here is a list
of subchunks supported by the exporter.
refc - This is the reference (or diffuse) color of the material.
refm - This is the reference (or diffuse) coefficient that factors the color.
ambc - This is the ambient color of the material.
ambm - This is the ambient coefficient that factors the color.
spcc - This is the specular color of the material.
spcm - This is the specular coefficient that factors the color.
lumc - This is the luminous color of the material.
lumm - This is the luminous coefficient that factors the color.
tndx - This is the index of refraction for the material.
rflm - This is the reflectivity coefficient for the material.
(By default the reflection color in EI is the diffuse color.)
flgc - This long holds "Color flags". The exporter sets flags to lock the specular
and/or luminous colors to the diffuse color.
The importer supports all of the chunks listed above. The
importer also reads in the other documented chunks although they
are not used.
MAPP (import/export) - The MAPP form contains information about
texture mapping.
TMAP (import/export) - To store information on texture maps EI
uses a TMAP chunk. TMAP chunks are associated with an object.
An object has one TMAP chunk for every texture that is applied to
it. This chunk contains information about the texture image such
as the dimensions of the bitmap image (this can be troublesome
for the exporter as it simply cannot reference a texture map and
output its name; rather, it must load the image header for the
file from disk to determine its dimensions so that the exporter
can store that information in the TMAP chunk). The TMAP chunk
also stores the type of projection to use when it is being mapped
onto the object. This seems like a very strange thing. Another
chunk (TMEI) stores information on what the projection looks like
but doesn't store the type of projection it represents! This is
why the TMAP appears before the TMEI in the file. The TMAP chunk
also includes information about the images bounding box.
TMEI (import/export) - Most of the information on texture
projection is stored in the TMEI chunk. However, as stated
before the actual type of projection stored in the TMEI chunk is
determined by the TMAP chunk. The data stored in the TMEI chunk
actually depends on the type of projection it is. The TMEI chunk
can represent four different projections:
- Flat
- Cylindrical
- Spherical
- Cubic
There are actually other experimental formats listed in the FACT
documentation. However, they are not supported in this
importer/exporter since the formats were not described in the
FACT documentation nor available within EI.
CORD/DCORD (import/export) - All of the coordinates that compose
an object are output in a CORD chunk. For example, a cube would
have 8 coordinates output. The exporter determines the objects
bounding box as the CORD chunk is being output for greater
efficiency. The bounding box is later stored in the GINF chunk.
The importer is able to read CORD or DCOR chunks.
BVRT (import/export) - The BVRT chunk stores bump vertices.
CVRT (import/export) - The CVRT chunk stores color vertex
information. The colors are stored as ARGB values. That is 4
bytes with one byte for alpha, red, green and blue.
NVRT (import/export) - The NVRT chunk stores normal vertices.
TVRT (import/export) - The TVRT chunk stores texture vertices or
UV coordinates. However, the EI format doesn't have any way of
actually enabling this information for texturing. It is up to
the user to enable UV mapping within the UI. The option is
located in EI under "Shading" for the object. This importer and
exporter support the TVRT chunk, but it is not very useful since
the user has to do a lot of work to enable UV's and then apply a
texture. It is possible that EI may add support for this in the
future.
PFAB (export) - This chunk is not documented but it appears to be
very important in specifying how a texture modulates a layer.
From the spec it appears that flags in the TMAP chunk are used to
specify the modulation type. However, E.I. seems to ignore this
information. Instead, it reads the PFAB chunk for this info.
The PFAB chunk is only 4 bytes long. In all of the cases we have
observed, it is all zeros except for the last byte which varies
depending on the type of modulation.
- For bump map: 00 00 00 01
- For diffuse: 00 00 00 05
- For ambient: 00 00 00 06
- For specular: 00 00 00 07
- For transparency: 00 00 00 08
- For luminous: 00 00 00 09
The exporter sets the TMAP flags and also writes a PFAB chunk.
We mimick the behavior of EI with sane values for these
parameters. The importer uses only the TMAP chunk for
determining the modulation type. The documentation lists pfab
but the chunk name is PFAB.
Note about importing: The importer currently does not make use
of the PFAB chunk. This is because the information contained in
the PFAB is also contained in the TMAP as part of the textureFlag
element. Since TMAP should always be present when texturing is
enabled, this information is used instead of PFAB.
DSPL (export) - This chunk appears in a MAPP form that is bump
mapped. In files we have observed the chunk data is all zeros.
The data is ignored by the importer.
Overview