BRL-CAD Tutorial Series: Volume IV - Converting Geometry Between BRL-CAD and Other Formats


Dedication.  The authors would like to thank Messrs. Lee Butler, Edwin Davisson, William Landis, and David Davis for technically reviewing this document in a timely manner and for making numerous suggestions to improve its content and presentation. The authors also thank Dr. Paul Tanenbaum for the use of his graphics for figures 1 and 2 and Ms. TraNese Christy for her help in adapting them for presentation in this document. Finally, the authors would like to posthumously acknowledge Mr. Michael Muuss, the original architect of BRL-CAD. Without his vision, intellect, and diligence, this work would not have been possible. Thus, the BRL-CAD Tutorial Series is dedicated to his memory.

Table of Contents

1. Introduction
1.1. Background, Purpose, and Scope
2. Pertinent Characteristics of the BRL-CAD Format
2.1. CSG vs. BREP
2.2. Prerelease 6.0 Database vs. Current Format
2.3. Converters Currently Available in BRL-CAD
3. Converting From/to ASCII
3.1. Converting From ASCII
3.2. Converting to ASCII
4. Converting to BRL-CAD
4.1. General Information About Converting to BRL-CAD
4.2. Converting From AutoCAD DXF Format
4.3. Converting From Elysium Neutral Facetted Format
4.4. Converting From EUCLID Format
4.5. Converting From FASTGEN Format
4.6. Converting From IGES Format
4.7. Converting From Jack
4.8. Converting From NASTRAN Format
4.9. Converting From Pro/E Format
4.10. Converting From STL Format
4.11. Converting From TANKILL Format
4.12. Converting From Unigraphics Format
4.13. Converting From Viewpoint Datalabs Format
5. Converting From BRL-CAD
5.1. General Information About Converting From BRL-CAD
5.2. Converting to ACAD Format
5.3. Converting to AutoCAD DXF Format
5.4. Converting to EUCLID Format
5.5. Converting to IGES Format
5.6. Converting to Jack
5.7. Converting to STL Format
5.8. Converting to TANKILL Format
5.9. Converting to VRML Format
5.10. Converting to Wavefront Format
5.11. Converting to X3D Format
6. Building a New Converter
6.1. General Information About Building a New Converter
6.2. Converting From BRL-CAD
6.3. Converting to BRL-CAD
7. Postconversion Issues

List of Figures

2.1. CSG and BREP approaches to representing an extrusion die (Tanenbaum, 2001).
2.2. Approximating a smooth, curved surface (left) with a BOT (right) (Tanenbaum, 2001).
4.1. Converter dialog box

List of Tables

2.1. BREP Terminology
2.2. CSG or BREP?
2.3. What About Databases in the Old Format?
2.4. BRL-CAD conversion capabilities.
4.1. BRL-CAD import converters
4.2. NMG Primitive
4.3. Part name mapping
4.4. Header file note
4.5. Keys to Converting Pro/E Geometry
5.1. BRL-CAD export converters.
5.2. ACAD or AutoCAD?
5.3. Package-Preferred IGES Converter Options
5.4. The Web3D Consortium

Since 1979, the U.S. Army Research Laboratory[1] has been developing and distributing the Ballistic Research Laboratory - Computer-Aided Design (BRL-CAD) three-dimensional (3-D) solid modeling package to support combat vehicle vulnerability studies and various other military and industrial applications. The software, which is now in its third generation, includes a large collection of tools and utilities, including an interactive geometry editor, raytracing and generic framebuffer libraries, network-distributed image-processing/signal-processing capabilities, and an embedded scripting language.

In support of the package, a multivolume tutorial series is being written to assist users with the many features and functionality of BRL-CAD. Three volumes have been published thus far. Volume I provides an overview of the package contents and installation (Butler and Edwards, 2002). Volume II addresses the basic functionality of the package's Multi-Device Geometry Editor (MGED) and offers a comprehensive list of the user commands available (Butler et al., 2001). Volume III discusses the modeling process as well as principles and techniques to help maximize BRL-CAD's effectiveness (Butler et al., 2003). All of these documents are available for download at http://ftp.arl.army.mil/brlcad/ (U.S. Army Research Laboratory, 2003).

The purpose of Volume IV is to discuss issues of compatibility and conversion between the BRL-CAD geometry file format and the formats of various other computer-aided design (CAD), computer-aided manufacturing (CAM), and computer-aided engineering (CAE) packages. Conversion is increasingly important for BRL-CAD users who must interact with a growing number of Government and commercial organizations involved in the research, development, testing, and evaluation of today's combat systems.

Note that this document addresses BRL-CAD geometry converters, not BRL-CAD image converters (e.g., pix-bw, pix-ps, pix-rle, bw-ps, and pl-ps). For further information on image conversion, see the man page on the utility of interest.

Also, because of the many file formats in existence today and the rapidly changing nature of computer software and software companies, it would be impractical to try to address all of the conversion paths and methods that are currently or potentially possible. Many times, conversion from one file format to another is not a one-to-one process. Depending on the amount of time and effort the BRL-CAD user is willing to invest, seemingly incompatible formats can be ``forced'' to convert via another CAD format or via a standardized CAD format (e.g., the Initial Graphics Exchange Specification [IGES] or the Standard for the Exchange of Product Model Data [STEP]). In fact, when it comes to converting from BRL-CAD, the widely accepted Stereo Lithography Tessellation Language (STL) format offers a crude path to convert BRL-CAD objects to virtually any commercial CAD system. The user is reminded, however, that such forced conversions can sometimes produce geometry of such poor quality (e.g., low-resolution or lossy output formats) or poor performance characteristics (e.g., large or computationally intensive output files) that completely rebuilding a model from scratch might be a preferable alternative.

In any case, the focus of this document is on the primary formats that convert to and from BRL-CAD. Chapter 2, Pertinent Characteristics of the BRL-CAD Format discusses pertinent characteristics specific to the BRL-CAD format. Chapter 3, Converting From/to ASCII addresses general conversion to/from the American Standard Code for Information Interchange (ASCII) format. Chapter 4, Converting to BRL-CAD addresses the primary formats that convert to BRL-CAD. Chapter 5, Converting From BRL-CAD addresses the primary formats that convert from BRL-CAD. Chapter 6, Building a New Converter provides guidance for those users who desire to create their own customized converters. And Chapter 7, Postconversion Issues addresses postconversion issues. In addition, the user is encouraged to consult the web sites and other resources cited at the end of each converter discussion to obtain the latest information on each format.

Since its inception, BRL-CAD has proven itself to be a particularly effective tool for producing high-resolution and physically realistic geometry for ballistic penetration, radar signature, and other types of related analyses. However, several commercial CAD packages have also gained popularity, especially within organizations that design and manufacture military systems. Although these packages are not designed for vulnerability studies per se, their widespread use throughout military circles necessitates that BRL-CAD users be able to convert to and/or from them.

There are numerous benefits associated with the use of commercial packages in vulnerability studies. The Survivability/Vulnerability Information Analysis Center (SURVIAC) identified some of the most common benefits in its 2002 State-of-the-Art Report (SOAR) on geometric modeling. They include the following (SURVICE Engineering Company, 2002):

Of course, commercial CAD packages also have some common liabilities when used for vulnerability studies. They include the following (SURVICE Engineering Company, 2002):

  • Incompatible/Inaccessible File Formats - As discussed in Chapter 2, Pertinent Characteristics of the BRL-CAD Format, some CAD formats use the boundary representation (BREP) approach to solid modeling, which is largely incompatible with the constructive solid geometry (CSG) approach that BRL-CAD uses. In addition, although most commercial packages have some capability for data exchange conversion, data storage is often in a proprietary (and therefore inaccessible) native format. Moreover, when target descriptions are converted to a format designed for vulnerability assessment (i.e., BRL-CAD or FASTGEN), they often require manual checking, adjustment, and additional modeling (see Chapter 7, Postconversion Issues). Typical problems that must be addressed include the translation of curved and irregular surfaces, the representation of solids of rotation, tolerancing, and interference handling.

  • Too Much Detail - Commercial geometry files often contain too much of a good thing for vulnerability analysis. That is to say, commercial CAD packages often model geometry all the way to the ``nuts and bolts'' level, whereas vulnerability analyses are typically concerned only with details down to the level of shielding and critical components. Unfortunately, added detail produces unnecessarily large and complex input files and thus longer processing times for vulnerability assessments.

  • Too Little Detail - In addition to providing too much detail, commercial packages sometimes provide too little detail for vulnerability studies. Vulnerability analysts and the applications designed to interrogate geometry rely on geometric measurements and material properties not always present in commercial CAD formats.

  • Package-Specific Naming Conventions - Some organizations and CAD packages use unique object naming schemes that make geometry difficult to organize and work with when converted to or from BRL-CAD format.

  • Relatively Slow Raytracing Capability - Commercial CAD packages typically have relatively slow raytracing speeds, and raytracing is the primary means of geometry interrogation in vulnerability assessment.

  • Limited Integrated Vulnerability Assessment Support - Commercial CAD packages are designed for engineering analysis, not ballistic analysis and therefore offer few, if any, ``shotlining'' tools and limited integrated vulnerability assessment support.

  • High Cost - In addition to facing the typically high cost of commercial CAD software, the user often faces the decision of whether or not to invest in non-PC hardware (e.g., UNIX workstations) to obtain maximum performance, especially with large, complex geometry. In addition, users may be required to pay continuing licensing and maintenance fees, often on a per-seat basis (although recent developments have offered PC-based implementations and short-term leasing ``seats'' to make these packages more affordable).

Not surprisingly, when considering the benefits and liabilities of using commercial packages in vulnerability assessment, one can see that the conversion of these formats to/from BRL-CAD is one of the most needed as well as one of the most challenging tasks the BRL-CAD user faces today.



[1] On 30 September 1992, the U.S. Army Ballistic Research Laboratory (BRL) was deactivated and subsequently became part of the U.S. Army Research Laboratory (ARL) on 1 October 1992.

As mentioned previously, there are two basic approaches to solid modeling: CSG and BREP. In CSG modeling, an object is represented as a Boolean combination of simple primitive shapes (e.g., spheres, cylinders, cones, etc.). In BREP modeling, an object is represented by a set of surfaces (e.g., facets, triangles, and splines) that are ``stitched'' together to completely enclose the object.

For example, as shown in Figure 2.1, “CSG and BREP approaches to representing an extrusion die (Tanenbaum, 2001).”, to geometrically represent a simple extrusion die used in material manufacturing, a CSG model might subtract a cone from a cylinder to achieve the desired shape. Alternatively, a BREP model might achieve the same shape by joining several surfaces (Tanenbaum, 2001).


Most of the major commercial solid modeling packages currently in distribution (e.g., Pro/ENGINEER [commonly known as Pro/E], Unigraphics, etc.) use the BREP approach, although they do have some CSG capability. BRL-CAD, on the other hand, is primarily a CSG modeling system with some BREP capability.

Conversions that occur between CSG and BREP typically involve their ``lowest common denominator.''

For BRL-CAD, a simple type of BREP is available in the form of triangles; it is called the Bag of Triangles (BOT) primitive. If the BREP object consists of all triangles, the BRL-CAD representation can be an exact duplicate. But more often, a BREP object consists of smooth, curved surfaces, meaning the BRL-CAD triangle representation will be an approximation of the object. Note that this approximation may be made as close to the true surface as desired, but at the cost of more, smaller triangles (see Figure 2.2, “Approximating a smooth, curved surface (left) with a BOT (right) (Tanenbaum, 2001).”) (Tanenbaum, 2001). Thus, the higher degree of smoothness means the greater the impact on file size and performance of any application trying to employ all the triangles.

Because most commercial CAD systems have the capability to produce tessellated approximations of their BREP objects, some converters to BRL-CAD (e.g., those with Pro/E and Unigraphics) take advantage of these capabilities. In addition, the previously mentioned STL format, which represents solid objects entirely with triangles, offers the community a universal (albeit crude) way to convert BRL-CAD geometry (via the g-stl converter) to nearly any commercial CAD system.



In the end, although there are benefits to using the BREP methodology (e.g., ease of use, software availability/compatibility, etc.), BRL-CAD developers and vulnerability analysts have found CSG modeling to be the best approach in terms of model accuracy, storage efficiency, precision, and analysis speed.


With the release of BRL-CAD 6.0, an entirely new BRL-CAD database format was introduced. Additional capabilities provided by the new format include unlimited name lengths, object attributes, machine independence (for IEEE floating point architectures), reduced disk space requirements, opaque binary objects, and the capability to hide objects. (For more information on the new database format, see Butler et al. [2003]).

Older BRL-CAD databases may be upgraded to the current database (db) format using the dbupgrade utility. To execute this command, the user types the following command at the command-line prompt:

dbupgrade oldformat.g currentformat.g

This command reads an existing input.g database (in the older format) and writes a new output.g in the latest format. Remember that all BRL-CAD geometry files are designated by a ``.g'' suffix. Thus, the conversion commands discussed in the following sections use a ``g'' to represent the BRL-CAD file format (e.g., asc2g, dxf-g, g-acad, etc.).


With the implementation of BRL-CAD's machine-independent database format, the need for converting to or from ASCII format has rapidly diminished. Nonetheless, BRL-CAD still supports ASCII conversions, and release 6.0 introduced a new ASCII format. This format is simply a Tcl[2] script that (when executed by a properly empowered Tcl interpreter) rebuilds the database from which it was derived. In contrast, the old ASCII format consisted of a sequence of one-line records that corresponded to the old database format records.



[2] Tcl/Tk is an interpreted programming language that can be used to extend/customize BRL-CAD functionality. Users are encouraged to consult one of the many texts on Tcl/Tk syntax and use, including Practical Programming in Tcl and Tk (Welch, 1999) and TCL/TK in a Nutshell (Raines and Tranter, 1999).

DXF is Autodesk Inc.'s proprietary data specification that has been developed to support links with AutoCAD, the company's popular CAD software. The format, which has been implemented in many CAD systems (particularly those that work on PCs), is simple and relatively limited; however, it has become a well-established means of exchanging engineering drawings.

The DXF format allows for the specification of the units used in the DXF file; however, not all DXF files include this information. Thus, if units information is not found in the DXF file, millimeters (which is also the default and underlying unit of measure in BRL-CAD) is the assumed unit of measure. Of course, if millimeters is not the right choice for a particular user or application, the -s (scale) option can be used. This option and the other available options for the dxf-g converter are discussed in the text that follows.

When using this converter, polygons and meshes are converted to BOT primitives. Each layer becomes a region. Lines, circles, and arcs become n-manifold geometry (NMG) objects, and points become spheres.


The command for the dxf-g converter is as follows:

dxf-g [options] input.dxf output.g

The options for the command are as follows:

  • -c - specifies that only the first color encountered for a layer in the DXF file is used; additional colors for the same layer are ignored.

  • -d - debug; produces core dump on failure.

  • -s - applies the specified scale factor to the DXF data (takes an argument).

  • -t - sets tolerance distance (in millimeters) (default is 0.005) (takes an argument).

  • -v - verbose; prints out progress information.

For more information on the DXF file format and import possibilities, see the on-line documentation on the Autodesk web site at http://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf (Autodesk, 2003).

Elysium Inc. was founded in 1984 to provide product structure synchronization and compatibility between different CAD systems. The company claims to hold the industry's highest translation success rate and relies on three of its products (CADporter, CADdoctor, and CADserver) to convert geometry between a large number of formats, including Pro/E, Unigraphics, ABAQUS/CAE, ACIS, CATIA, Inventor, I-deas, Metrix Build!IT, One Space Designer, Parasolid, and SolidWorks (Elysium, 2003).

The enf-g converter was originally written when BRL-CAD developers needed an intermediate format-the Elysium neutral facetted file format-to allow the conversion of Unigraphics geometry to BRL-CAD. The converter converts each part to a BRL-CAD region consisting of one BOT primitive. Ident numbers are incremented for each region. If a part name mapping file is provided, part names in the input file will be output using the corresponding names from the mapping file. The part name mapping file may look similar to the following:


The syntax for the enf-g command is as follows:

enf-g input_file output.g

The options for the command are as follows:

  • -i starting_ident - sets the starting ident number (default is 1000).

  • -n part_name_mapping - sets the mapping from input names to output names.

  • -t tolerance_distance - sets distance calculation tolerance (in millimeters) (default is 0.005).

For more information on the Elysium file format and import possibilities, see the Elysium web site at http://www.elysiuminc.com (Elysium, 2003).

EUCLID is one of Europe's primary product design, manufacturing, and engineering CAD packages (though it is quickly being superceded by CATIA). Formerly distributed by the European Aeronautic Defence and Space Company's Matra Datavision subsidiary and now a product of the IBM subsidiary MDTVISION, the package was developed for the design and manufacture of complex models and has been used on major systems such as the Airbus, Eurocopter, Ariane, Eurofighter, Astrium, and Euromissile.

Package features include specialized applications for design, styling, drafting, analysis, machining, and product data management. Recent enhancements have focused on automatic creation of 2-D drawings from 3-D models, milling cycles, two- to four-axis wire cutting, sheet metal design, mold design, and standard data exchange format interfaces.

EUCLID offers several data translation interfaces, including those for DXF, IGES, VDA-FS, STL, and SET formats. In addition, other modules are available to help refine and customize data transfer, with direct connectivity at two levels available for CATIA (V4/V5) data transfer using BREPs to handle surface data. EUCLID geometry can be output to standard graphic (e.g., PostScript, Encapsulated PostScript, and Interleaf) and plotting (e.g., CalComp, HP, HP/GL2, OCE, and Versatec) formats as well as to an STL file.

The euclid-g converter converts an ASCII EUCLID ``decoded'' format file to BRL-CAD. Each part is converted to a BRL-CAD region consisting of a single BOT primitive.

The syntax for the converter is as follows:

euclid-g [options]

The options for the command are as follows:

For more information about the EUCLID file format and import possibilities, see the MDTVISION web site at http://support.mdtvision.com (MDTVISION, 2003).


Developed by the Falcon Research and Development Company over 30 years ago, FASTGEN has been widely used in the Department of Defense air combat system assessment community (e.g., the Air Force Research Laboratory, the Joint Technical Coordinating Group for Munitions Effectiveness, and the Joint Technical Coordinating Group on Aircraft Survivability. Now distributed by the Survivability/Vulnerability Information Analysis Center (SURVIAC) as part of the Vulnerability Modeling Tool Set, the FASTGEN format uses geometry BREP based on NASTRAN, with data presented in a generic, open text-based file format.

Components of a target are represented in FASTGEN by triangles, quadrilaterals, cones, cylinders, spheres, and hexahedrons. These basic elements are designated as either plate (hollow) or volume (solid) mode and combined using a hierarchical structure for the formation of components and groups (SURVICE Engineering Company, 2002).

Notable aerospace firms and support organizations that use FASTGEN include Lockheed Martin, Boeing, Bell Helicopter, Northrop Grumman, Pratt & Whitney, General Electric, KETRON, ITT, BAH, SURVICE Engineering, and ASI.

There are several versions of FASTGEN currently in use. FASTGEN converters include FASTGEN4 and preprocessed FASTGEN Version 3 (also referred to as PATCH).

The patch-g converter converts preprocessed FASTGEN version 3 files to BRL-CAD format. The syntax for the command is as follows:

patch-g [options] output.g

The options for the command are as follows:

For more information about the FASTGEN file formats and import possibilities, see the SURVIAC web site at http://www.bahdayton.com/surviac/fastgen.htm (SURVIAC, 2003).

IGES was developed in 1979 by a consortium of government, industry, and academia representatives. Originally intended to provide a means of exchanging graphics and engineering drawings, IGES was extended to include solid models as well. This specification includes so many different implementations within itself that conversion between IGES flavors has become a small industry. Thus, conversion to/from IGES is a ``hit-or-miss'' proposition (NIST, 2003).

The Product Data Exchange using STEP specification is intended to replace IGES and correct the aforementioned deficiency by explicitly identifying different types of conversion and requiring converters to conform to those types. BRL-CAD supports conversion of two implementations of IGES, entirely facetted BREP and CSG with facetted BREP primitives.

The syntax for the iges-g converter is as follows:

iges-g [options] -o output.g input.iges

The options available for this command are as follows:

The -n, -d, -t, and -3 options are mutually exclusive. If none of these four options is provided, the default action is to convert only IGES solid model entities (CSG and planar face BREP) to BRL-CAD.

For more information about the IGES file format and import possibilities, see the National Institute of Standards and Technology (NIST) web site at http://www.nist.gov/iges (NIST, 2003).

Jack is a 3-D interactive ergonomics and human factors CAD package developed by the University of Pennsylvania's Center for Human Modeling and Simulation. Now maintained and distributed by Electronic Data Systems (EDS) (the company that now also distributes Unigraphics and NASTRAN), the package enables users to study and improve the ergonomics of product design and workplace tasks through the positioning of biomechanically accurate digital humans of various sizes in virtual environments. Jack and Jill digital ``humans'' can tell engineers what they can see and reach, how comfortable they are, when and why they're getting hurt, when they're getting tired, and other important ergonomics information. The package's principal features include a detailed human model, realistic behavioral controls, anthropometric scaling, task animation and evaluation systems, view analysis, automatic reach and grasp, and collision detection and avoidance (The University of Pennsylvania, 2001; EDS, 2003a).

The jack-g converter creates a single region consisting of a single BOT primitive. The syntax for the converter is as follows:

jack-g [options] input.jack output.g

The options for this command are:

For more information on the Jack file format and import possibilities, see the EDS web page at http://www.eds.com/products/plm/efactory/jack/ (EDS, 2003a).

Originally developed under National Aeronautics and Space Administration (NASA) sponsorship in the mid-1960s, the NASA Structural Analysis (NASTRAN) program was one of the first efforts to consolidate structural mechanics into a single computer program. It has since been used as a general-purpose software tool in numerous industries, including aerospace, automotive, medical, heavy machinery, electronic devices, and consumer products. The program is developed and distributed by the MSC.Software Corporation (MSC) and (as of June 2003) the EDS Corporation. It employs advanced finite element analysis computational techniques to analyze material strength/performance and evaluate static structures and the dynamic motion of structures (SURVICE Engineering Company, 2002; MSC.Software Corporation, 2003).

NASTRAN's nonlinear analysis capabilities can address a wide range of static and dynamic problems exhibiting both material and geometric nonlinear behavior. Heat transfer problems can also be solved using conduction, convection, and radiation methods under a variety of applied loads and boundary conditions.

The NASTRAN finite element modeling program is one of the general-purpose structural analysis programs used worldwide. Even though it was originally intended for structural analysis problems, its current applications include aeroelasticity, heat transfer, fluid structure interaction, acoustics, electromagnetics, and many other applications.

NASTRAN includes a file specification for describing geometric data. NASTRAN's wide use and adoption by CAD vendors make it well suited as a file standard.

The nastran-g converter currently only converts CBAR, CROD, CTRIA3, and CQUAD4 elements of NASTRAN files to BRL-CAD format. CBAR and CROD elements become cylinders in BRL-CAD. CTRIA3 and CQUAD4 elements become BOT facets.

The syntax for the converter is as follows:

nastran-g [options]

The options for the command are as follows:

For more on the NASTRAN file format and import possibilities, see the MSC web site at http://www.mscsoftware.com (MSC.Software Corporation, 2003) and the EDS web site at http://www.eds.com/products/plm/nastran/ (EDS, 2003b).

Distributed by the Parametric Technology Corporation (PTC), Pro/E is one of the most widely used commercial CAD packages for designing, engineering, and manufacturing products. The long list of major corporations that use Pro/E software for Product Lifecycle Management includes Boeing, Rolex, Audi, Dell, Nike, Maytag, Braun, and Hewlett-Packard (PTC, 2003).

Because of Pro/E's popularity in the Defense community, the Pro/E-to-BRL- CAD converter is one of the most important conversion utilities that BRL- CAD offers. Note that unlike the converters for other formats, the Pro/E converter is no longer command-line activated. This converter was written using the Pro/Toolkit module of Pro/E and therefore runs as part of the Pro/E program and GUI.

Accordingly, in order to use the converter, the user must have a seat of Pro/E as well as the BRL-CAD distribution. Currently, the converter is only supported on Silicon Graphics (SGI) machines with MIPS processors running the Irix operating system. The source code for this converter is included in the binary distribution, so users can compile it for different platforms if they have the Pro/Toolkit module for that platform.

Pro/E models are made up of two elements: parts and assemblies. Part files (which are designated by a .prt extension) are the basic building blocks of Pro/E geometry. Assembly files (which are designated by a .asm extension) are composed of parts and/or other assemblies. The converter produces a BRL-CAD region for each Pro/E part that is converted and a BRL- CAD combination for each Pro/E assembly that is converted. Each of these regions will consist of a single BOT primitive.

The conversion of geometry from Pro/E to BRL-CAD is a two-stage process. This converter first produces the ASCII form of BRL-CAD databases. The user then converts these databases to binary form using the asc2g utility.

In addition, because Pro/E files for most combat vehicles are so large (often requiring a stack of CDs to store them), entire geometries typically cannot be loaded all at once. Thus, the BRL-CAD user often has to convert geometry system by system (e.g., engine, transmission, and suspension) and then concatenate (i.e., join) them together in a single BRL-CAD geometry file. For more detailed information about this process, see the discussion on dbconcat in Volume III of this tutorial series.

Pro/E makes extensive use of referenced geometry. As discussed in the previous volume of this tutorial series (see section 5 of Butler et al. [2003]), referencing is the method by which multiple occurrences of objects are created by referring to a single object numerous times with different orientations and locations for each reference. These references are duplicated in BRL-CAD using combinations and transformation matrices. In some cases-such as when geometry is used with vulnerability codes that require each region to have a unique ident number-users may need to use the xpush command in MGED after the conversion is complete to replace the references with real geometry. For more information about this procedure, users should consult MGED's on-line help or the xpush entry in volume II of this tutorial series (see appendix A of Butler et al. [2001]).


The command to start the Pro/E program is specified by each installer. When Pro/E is started, the program looks for a file named protk.dat in a few specific places, one of which is in the current directory. This file informs Pro/E about Pro/TOOLKIT modules it should load. There is a protk.dat file for the Pro/E-to-BRL-CAD converter, and it is included in the distribution under the pro-engineer directory. Users should copy this file to the directory where they will be starting Pro/E. After that file is in place, Pro/E will load the converter at startup. If the loading succeeds, users will see a message saying ``Installation of Proe-BRL converter succeeded.'' With Pro/E started and the converter module loaded, the user can open any Pro/E model he wants to convert.

The conversion process is started by selecting the ProE-BRL item in the Pro/E drop-down File menu. The converter dialog box, shown in Figure 4.1, “Converter dialog box”, will then appear.


The following list provides a description of the use and functionality of the primary elements in the dialog box. Note that the box is preloaded with reasonable defaults for many of the inputs. In addition, if the user has a question about any of the entry windows, check boxes, or buttons, he can move the mouse over them to see a brief explanation of their use.

  • Output File Name - This is the name of the file to receive the ASCII output.

  • Log File Name - If provided, verbose status logging will be written to that file.

  • Part Name File - If provided, the converter will use that information to map Pro/E part and assembly names into the specified BRL-CAD object names. This file is simply a text file with each line specifying a Pro/E part or assembly name and a BRL-CAD object name separated by white space. Note that the BRL-CAD names should not include any special characters such as ``/'', ``['', ``]'', or white space.

  • Starting Ident Number - Ident numbers will be assigned to the resulting BRL-CAD regions sequentially starting with the number that appears in the window.

  • Max Tessellation Error - This value (expressed in millimeters) is used to control the coarseness of the tessellation. It is the maximum distance between the actual surface and its tessellated approximation. Smaller values here will result in finer tessellations and more triangles. The default value is reasonable for ballistic vulnerability analysis purposes.

  • Angle Control Value - This is a number between 0 and 1 that provides additional control over the coarseness of the tessellation. The exact relationship between the tessellation and this value is not specified in the Pro/E documentation, but the default value of 0.5 seems to work well.

For more information about the Pro/E file format and import possibilities, see the Parametric Technology Corporation (PTC) web site at http://www.ptc.com (PTC, 2003).

The STL format was developed by 3D Systems, Inc., in the 1980s for use with its StereoLithography Apparatus (SLA). The SLA device produces a physical 3-D model based on an STL format file. Because of its simplicity, the STL format has become an industry standard for exchanging 3-D models. Unfortunately, this simplicity also presents some limitations.

The format consists only of triangles, and each triangle is represented by three vertices and a surface normal vector. Because the vertices for each triangle are explicitly listed, rather than indexed from a list, the topology must be inferred by the receiving system, which can sometimes lead to incorrect geometry.

STL files may be either ASCII or binary. The ASCII format includes the capability of including more than one solid part and an optional name for each part, while the binary format can only support a single solid part with no naming.

The stl-g converter converts STL format to BRL-CAD. The STL format is entirely triangles. The resulting BRL-CAD database will consist of one or more regions and a top-level combination named ``all,'' which contains all the regions produced. Each region will consist of a single BOT primitive.

Note that the ASCII format STL file includes a capability to contain more than one solid part. The regions created will be named according to the name specified in the STL file unless a name is provided on the command line. If the STL file does not specify any name, and the user does not provide a name, then the regions produced in the BRL-CAD database will be constructed from the name of the STL file.

The syntax for the stl-g converter is as follows:

stl-g [options] input.stl output.g

where input.stl is the STL file to be converted and output.g is the name of the BRL-CAD database to receive the converted output.

The options for this command are as follows:

For more information on the STL file format and import possibilities, see the 3D Systems web site at http://www.3dsystems.com (3D Systems, 2003).

Like Pro/E, Unigraphics is a widely popular CAD format used by thousands of companies in the United States and abroad, including General Motors, Ford, Kodak, General Electric, Pratt & Whitney, Boeing, and Samsung. Now distributed by EDS (the company that also distributes Jack and a version of NASTRAN), the Unigraphics toolset addresses traditional CAD/CAM/CAE, conceptual and industrial design, knowledge-based engineering, real-time design collaboration, and process automation (EDS, 2003c).

There are three modeling methodologies offered with Unigraphics. First, explicit (or traditional) modeling uses points, curves, and surfaces with no associativity or history. Second, history-based modeling uses associative geometric entities. Third, direct modeling uses a combination of both explicit and history-based modeling and also allows the global application of geometric rules and constraints across geometry of all origins (SURVICE Engineering Company, 2002).

Unigraphics bases its component geometric modeling capabilities on the Parasolid geometry engine (developed by EDS in Cambridge, England) and related XT file format. This enables Parasolid-based systems (e.g., Unigraphics, Solid Edge, and systems by Parametric Technology, SolidWorks, Bentley Systems, CADKEY, ANSYS, Mechanical Dynamics, and MSC.Software) to share and exchange geometric data without translation via an interoperable data pipeline (SURVICE Engineering Company, 2002).

Because the Unigraphics-to-BRL-CAD converter, ug-g, was written using the Unigraphics UG/Open API library, users must have a Unigraphics UG/Open execute or development license in order to run it. This converter is compiled for SGI Irix machines running on MIPS processors; however, users can compile it for other platforms by obtaining the BRL-CAD source distribution and a UG/Open development license from Unigraphics.

This converter creates a BRL-CAD region consisting of a single BOT primitive for each Unigraphics part and a combination for each Unigraphics assembly. Each instance of a Unigraphics part is converted independently, so there are no transformation matrices created in the resulting BRL-CAD model. The BRL-CAD regions are given the same name as the parts are assigned in the Unigraphics model, unless a part-name mapping file is provided. Region names are made unique, if necessary, by adding a suffix consisting of a dot and an integer number.

The syntax for this converter is as follows:

ug-g [options] -o output.g UG_part_file [subpart1 subpart2 ...]

where the UG_part_file is a Unigraphics part file. If subparts are listed on the command line, only those named parts in the specified part file will be converted.

The available options are as follows:

For more information on the Unigraphics file format and conversion potential, see the EDS web site at http://www.eds.com/products/plm/unigraphics_nx/ (EDS, 2003c).

Table 5.1, “BRL-CAD export converters.” contains the primary file formats (other than ASCII) to which BRL- CAD currently converts. Once again, the "g-" designation at the beginning of each converter name indicates that the conversion process begins with BRL-CAD's standard geometry (.g) format.

Note that most of the BRL-CAD export converters operate by tessellating all the primitive shapes in the BRL-CAD model, then evaluating the Boolean formula for each region. The result of this is a facetted representation of each region. The tessellation tolerances are used to determine the coarseness of the tessellation of curved surfaces. Smaller tolerances result in more, smaller facets and a larger output file. The calculation tolerance is the minimum distance between any two vertices in a region. Any vertices closer than this are fused into a single vertex.


Occasionally, the Boolean evaluation process will fail. When this happens, an error message specifying the region that failed to convert will be generated. The converter will then proceed to work on the next region to be converted.

The Advanced Computer Aided Design (ACAD) format is the format for the in- house CAD package developed in the early 1980s by Lockheed Martin Tactical Aircraft Systems (then General Dynamics - Fort Worth) and distributed since 1995 by the Electromagnetic Code Consortium. The package was developed to improve the product design process by eliminating manual drawing boards and reducing design iteration cycle times. Notable aircraft programs that have used ACAD include the Joint Strike Fighter (F-35), the Raptor (F-22), the Advanced Technology Fighter, the National Aerospace Plane (X-30), and the Attack/Fighter-Experimental (A/F-X) (SURVICE Engineering Company, 2002).

A notable characteristic of ACAD is the layers by which modeled parts are separated and managed (e.g., by subsystem). The package stores geometric data in a relational database that uses parent-child dependencies to enable automatic and rapid geometric modification. For example, changing a control spline of a fuselage will automatically regenerate any surface(s) built with that spline. Any geometry that is associated to the fuselage surface (i.e., plane/curve and surface intersections, fillets, etc.) will then regenerate.

One of ACAD's strengths is its bidirectional IGES translator, which provides compatibility with other IGES-supported formats, including CADAM, CATIA, COMPUTERVISION, AutoCAD, and Pro/E.


As its name implies, the g-acad utility converts a file in BRL-CAD format to a file in facetted ACAD format. The form of the command is as follows:

g-acad [options] -o output_file input.g object(s)

The options for the g-acad command are as follows:

  • -i - designates that the output be in inches (the default is millimeters).

  • -x lvl - sets librt debug flag (see raytrace.h in the binary distribution for definitions of DEBUG_xxx).

  • -X lvl - sets the NMG library debug flag (see nmg.h in the binary distribution for definitions of DEBUG_xxx).

  • -e error_file - sends error messages to specified file (default is standard error [stderr]).

  • -v - verbose; prints out progress information.

  • -D tolerance_distance - sets distance calculation tolerance (in millimeters) (default is 0.005).

  • -r rel_tess_tol - sets relative tessellation tolerance (normally 0.0 to 1.0) (default is 0.1).

  • -a abs_tess_tol - sets absolute tessellation tolerance to specified value (in millimeters) (overrides -r option).

  • -n norm_tess_tol - sets surface normal tessellation tolerance (angle in radians) (overrides -r option).

For more information on the ACAD file format and conversion potential, contact Lockheed Martin Tactical Aircraft Systems at http://www.lockheedmartin.com (Lockheed Martin, 2003).

The syntax for the BRL-CAD to IGES converter is as follows:

g-iges [options] input.g object(s)

The options for the g-iges command are as follows:

With the -t and -f options, the converter will employ Boolean evaluation of each region. If neither option is specified, then a CSG IGES file will be produced. The command also accepts the previously mentioned -v, -r, -a, -n, -x, and -X options.


For more information about the IGES file format and export possibilities, see the NIST web site at http://www.nist.gov/iges (NIST, 2003).

The Virtual Reality Modeling Language (VRML) began in 1994 at the first World Wide Web Conference. The format -which is maintained by the nonprofit, vendor-neutral Web3D Consortium- was designed to be a Web-interoperable standard for specifying multiparticipant 3-D graphical visualization tools. When a user selects a hyperlink to a VRML document from within a correctly configured WWW browser, a VRML viewer is launched to navigate through a given geometry (e.g., a model of a building). Future versions of VRML are planned to include more advanced features, including animations, motion physics, and real-time multiuser interaction (Web3D Consortium, 2003b).

The g-vrml command converts BRL-CAD objects to the VRML 2.0 format. It takes the following form:

g-vrml [options] input.g object(s)

The options for the command are as follows:

The command also accepts the previously mentioned -v, -r, -a, -n, -x, and -X options.

For more information on VRML, see the Web3D Consortium web site at http://www.web3d.org /fs_technicalinfo.htm (Web3D Consortium, 2003b).


If the previously mentioned import/export converters do not meet the user's needs, a custom converter can be built. The effort required to accomplish this, of course, depends on the user's coding ability, the intended model use, and the available resources. If one needs to convert from a simple ASCII format consisting entirely of triangles to BRL-CAD, a few days of effort will probably suffice. On the other hand, if one wants to develop a converter from a proprietary commercial CAD system to BRL-CAD, several months of effort and training may be required.

For example, Pro/E, Unigraphics, and similar commercial CAD systems provide libraries and APIs that a developer can use to access their models. Typically, training is required in order to understand what these libraries can do and how they work, and training in the use of the CAD system itself may be required as a prerequisite to understand the package environment and terminology. The purchase of expensive licenses is also a typical requirement, and, in some cases, the use of the code developed will require the purchase of another license.

But before one begins developing a new converter, one should first consider the possibility of using combinations of existing converters. For example, if one needs to convert from a commercial CAD system to BRL-CAD and no converter exists for that system, he might consider importing his model into Pro/E or Unigraphics and converting to BRL-CAD from there.

Understandably, this may result in the loss of some information (and repeated conversions usually mean greater losses), but restoring that information manually may be more cost effective than building a new converter from scratch. Another possibility might be to convert the geometry to STL format and then convert the STL to BRL-CAD using stl-g (see Section 4.10, “Converting From STL Format”).

A similar situation exists for converting to BRL-CAD. If one is fortunate enough to be converting from a CSG system, then just converting everything to its corresponding BRL-CAD representation is all that is required. The libwdb library distributed with BRL-CAD contains all the routines needed to build primitives, regions, and combinations in BRL-CAD.

To create an empty BRL-CAD model, use the following code snippet:

      struct rt_wdb *wdbp;
      if( (wdbp=wdb_fopen( new_file_name ) ) == RT_WDB_NULL ) {
      bu_exit(1, "Failed to open output file (%s)\n", new_file_name);
      }

Then use the wdbp pointer to pass to all the routines in libwdb.

For example, to build a sphere centered at coordinates (1.0, 2.0, and 3.0) with a radius of 5.0 mm in BRL-CAD, the following call to mk_sphere will suffice:

char *sphere_name="s1";
      point_t center;
      fastf_t radius;
      /* set the center and radius values */
      VSET( center, 1, 2, 3 );
      radius = 5.0;


      /* actually build the sphere */
      if( mk_sph( wdbp, sphere_name, center, radius ) ) {
      bu_exit(1, "Failed to make a sphere (%s)\n", sphere_name ;
      }

To build a region or combination in BRL-CAD, a call to mk_comb will do the job. This is a bit more complicated as it requires building a list of members prior to the call to mk_comb. In the example that follows, a region consisting of primitive ``s2'' subtracted from primitive ``s1'' is constructed:

struct bu_list head;
      struct wmember *wmp;


      /* initialize the list of members for this combination */
      BU_LIST_INIT( &head );


      /* add the first member (use the UNION operator here) */
      if( (wmp=mk_addmember( "s1", &headp, NULL, WMOP_UNION) ) ==
      WMEMBER_NULL ) {
      bu_exit(1, "Failed to add member(s1)\n");
      }


      /* subtract the second member */
      if( (wmp=mk_addmember( "s2", &headp, NULL, WMOP_SUBTRACT) ) ==
      WMEMBER_NULL ) {
      bu_exit(1, "Failed to add member(s2)\n");
      }


      /* build the actual region */q
      if( mk_comb( wdbp, "region_name", &head, 1, NULL, NULL, NULL, 1000, 0,
      1, 100, 0, 0, 0 ) ) {
      bu_exit(1, "Error building region\n");
      }

If the system you are converting from is not a CSG system (which is the most likely case), then you will need to do some processing on the originating system to get the data in a form that BRL-CAD can use. If you have the API module for the originating system, you may be able to use one of those routines to create a triangulated representation of the model. This triangle data can then be used to build BOT primitives in the BRL-CAD model using the mk_bot routine. Each BOT primitive can be placed in a region of its own (as shown previously).

A hybrid approach is also possible where simple shapes that can be identified as BRL-CAD primitive shapes are converted as BRL-CAD primitives, and everything else is converted as BOT primitives. If the converter requires building BOT primitives, you might want to consider a converter that produces a BRL-CAD ASCII format database. The "C" mk_bot routine is a very thin wrapper for the actual internal format of the BOT primitive and requires an intimate knowledge of its structure. The ASCII format is considerably simpler and easier to work with in this situation. As mentioned previously, the current ASCII format is simply a Tcl script. For example, the following is the ASCII form of a BRL-CAD database containing a single BOT:

title {example of a simple BOT primitive}
      units mm
      put {tetra} bot mode volume orient rh flags {} V { { 0 0 1000 } { -500
      0 -1000 } { -500 -500 -1000 } { 500 -500 -1000 }} F { { 0 1 3 } { 0 1
      2 } { 0 2 3 } { 1 2 3 }}

The aforementioned example creates a BRL-CAD database with the title of ``example of a simple BOT primitive,'' with preferred units of millimeters and a single tetrahedron-shaped BOT primitive. The line that begins with ``put'' creates the BOT primitive (note that there are actually only three lines in this example; the last line is wrapped in this report for clarity). This line is a command to the Tcl interpreter. The ``put'' is the command, ``tetra'' is the name of the object to be created, and ``bot'' is the type of object to create. The remainder of the line consists of key/value pairs. This line creates a BOT primitive named ``tetra,'' using volume mode (meaning this BOT encloses space), with right-hand (rh) rule triangle orientation, and no flags.

The V key introduces the list of vertices for this BOT primitive, and the F key introduces the list of triangle faces (each integer is an index into the list of vertices). Additional put commands build more objects in the database. For example, to create a region using the tetra object, the user would append the following line to the aforementioned file:

put {aregion} comb region yes tree {l tetra}

This line creates a BRL-CAD combination named aregion, which is a region and consists only of the tetra object created earlier. The resulting file is converted to BRL-CAD binary format using asc2g.

For an example of code that produces this type of output, see the g2asc.c file in the conv directory of the source distribution.

Before converted geometry can be used in a given application or analysis (e.g., a vulnerability study), there are several tasks that often need to be performed. They include the following: