BRL-CAD Tutorial Series:

Volume I ñ Overview and Installation

by Lee A. Butler and Eric W. Edwards

 ARL-SR-113 February 2002

Approved for public release; distribution is unlimited.
The findings in this report are not to be construed as an official

Department of the Army position unless so designated by

other authorized documents.

Citation of manufacturerís or trade names does not constitute

an official endorsement or approval of the use thereof.

Destroy this report when it is no longer needed. Do not return

it to the originator.
!"#$%&'(')"*+%,)-.")/."$

Aberdeen Proving Ground, MD 21005-5068

!&,01&0223% %%%%%%%%4'-"5)"$%6776

BRL-CAD Tutorial Series:

Volume I ñ Overview and

Installation

Lee A. Butler

Survivability/Lethality Analysis Directorate, ARL

Eric W. Edwards

SURVICE Engineering Company

Approved for public release; distribution is unlimited.
ii

!-(/")*/

Since 1979, the U.S. Army Research Laboratory has been developing and

distributing the BRL-CAD constructive solid geometry (CSG) modeling package

for a wide range of military and industrial applications. The package includes a

large collection of tools and utilities including an interactive geometry editor,

raytracing and generic framebuffer libraries, a network-distributed imageprocessing and signal-processing capability, and an embedded scripting

language.

As part of this effort, a multivolume tutorial series is being developed to assist

users in the many features of the BRL-CAD package. The ìOverview and

Installationî guide, which is the first volume in the series, addresses the

background, purpose, and strengths of the package; the libraries and utilities

included within it; platform-specific installation instructions; and information

about bugs and updates. Other volumes focus on advanced features, individual

utilities, and programming.
iii

!*89.:;'<=#'9/(

The authors would like to thank the members of the Advanced Computer

Systems Team, who reviewed this document in a timely manner and made many

helpful suggestions to improve its accuracy and presentation. Team members

include John Anderson, TraNese Christy, Bob Parker, Ron Bowers, and Sean

Morrison.

In addition, the authors would like to especially acknowledge Mike Muuss, a

team member and the original architect of BRL-CAD, who passed away in the

fall of 2000. Without his vision, this work would not have been possible.

Therefore, the BRL-CAD Tutorial Series is dedicated to his memory.
iv

INTENTIONALLY LEFT BLANK.
v

>.9/'9/(

2? @9/".<5*/A.9 2

1.1 What Is BRL-CAD?........................................................................................ 1

1.2 Why CSG Modeling?..................................................................................... 1

6? B)*8)='%>.9/'9/ 6

2.1 Libraries........................................................................................................... 3

2.1 Tools and Utilities.......................................................................................... 4

3? @9(/);;)/A.9 C

3.1 Obtaining the Package .................................................................................. 5

3.2 System Requirements.................................................................................... 6

3.3 Irix 6.x .............................................................................................................. 6

3.4 FreeBSD ........................................................................................................... 8

3.5 Linux.............................................................................................................. 11

3.6 Solaris............................................................................................................. 13

3.7 Source Code .................................................................................................. 14

D? E'9*+#)"8%F'(/A9= 2G

C? H)A9/'9)9*'%)9<%IJ<)/'( 2K

5.1 Troubleshooting and Tracking Bugs......................................................... 18

5.2 New Releases................................................................................................ 18

L? &'M'"'9*'( 2N

!JJ'9<AOP%%E&,0>!Q%,A*'9('%!="''#'9/ 62

QA(/"A-5/A.9%,A(/ 6G

&'J."/%Q.*5#'9/)/A.9%4."# 6N
vi

INTENTIONALLY LEFT BLANK.
1

2? @9/".<5*/A.9

2?2 R+)/%@(%E&,0>!QS

Since the late 1950s, computers have been used to assist with the design and

study of combat vehicle systems. The result has been a reduction in the amount

of time and money required to take a system from the drawing board to fullscale production as well as increased efficiency in testing and evaluation.

In 1979, the U.S. Army Ballistic Research Laboratory (BRL) (now the U.S. Army

Research Laboratory [ARL]) expressed a need for tools that could assist with the

computer simulation and engineering analysis of combat vehicle systems and

environments. When no existing computer-aided design (CAD) package was

found to be adequate for this purpose, BRL software developers began

assembling a suite of utilities capable of interactively displaying, editing, and

interrogating geometric models. This suite became known as BRL-CAD.

Now comprising over one-half million lines of C code, BRL-CAD has become a

powerful constructive solid geometry (CSG) modeling package that has been

licensed at over 2,000 sites throughout the world. It contains a large collection of

tools, utilities, and libraries including an interactive geometry editor, raytracing

and generic framebuffer libraries, a network-distributed image-processing and

signal-processing capability, and a customizable embedded scripting language.

In addition, BRL-CAD simultaneously supports dual interaction methods, one

using a command line and one using a graphical user interface (GUI).

A particular strength of the package lies in its ability to build and analyze

realistic models of complex objects using a relatively small set of ìprimitive

shapes.î To do this, the shapes are manipulated by employing the basic Boolean

operations of union, subtraction, and intersection. Another strength of the

package is the speed of its raytracer, which is one of the fastest in existence.

Finally, BRL-CAD users can accurately model objects on scales ranging from the

subatomic through the galactic and get ìall the details, all the time.î

2?6 R+$%>1T%H.<';A9=S

Although BRL-CAD has been used for a wide variety of engineering and

graphics applications, the packageís primary purpose continues to be the

support of (1) ballistic and (2) electromagnetic analyses. Accordingly,

developers have found CSG modeling to be the best approach in terms of model

accuracy, storage efficiency, precision, and speed of computational analysis.
2

While polygonal and boundary representation (B-rep) modeling often focuses on

just the !"#$%&'! of objects, CSG modeling focuses on the entire ()*"+',and,&)-.'-.

of objects. This gives BRL-CAD the capability to be ìmore than skin deepî and

build objects with real-world materials, densities, and thicknesses so that

analysts can study physical phenomena such as ballistic penetration and

thermal, radiative, neutron, and other types of transport.

6? B)*8)='%>.9/'9/

In keeping with the UNIX philosophy of developing independent tools to

perform single, specific tasks and then linking the tools together in a package,

BRL-CAD is basically a collection of libraries, tools, and utilities that work

together to create, raytrace, and interrogate geometry and manipulate files and

data. The basic data flow structure of the package is provided in Figure 1.

Figure 1. BRL-CAD data flow structure.
3

6?2 ,A-")"A'(

The BRL-CAD libraries (designated by the prefix ìlibî) are designed primarily

for the geometric modeler who also wants to tinker with software and, perhaps,

design custom tools. Each library fits into one of three categories: (1) creating

and/or editing geometry, (2) raytracing geometry, or (3) image handling. The

following is a list of the major BRL-CAD libraries and descriptions of their

functions.

 ;A--5 ñ a basic utility (bu) library containing fundamental computer

science types of routines, including manipulating data (e.g., converting

from host format data to network format data), parallel processing,

parsing parameters, handling variable-length strings, performing error

checks, converting units from one format to another, manipulating bit

vectors, running parallel-safe versions of input/output (I/O) routines,

and maintaining symbol tables.

 ;A--9 ñ a library of routines to support basic numerical (bn) handling,

including 2-D/3-D vector, matrix, and quaternion manipulation; 3-D

plotting support; automatic inference of image size (BRL-CAD images

have no internal header; image dimensions are intuited from the size of

the file); and wavelet decomposition and reconstruction, etc.

 ;A-<# ñ BRL-CADís primary graphics display manager (dm) library. It

handles opening windows onto the display and displaying geometry in

the graphics window, etc.

 ;A-M- ñ the framebuffer (fb) library, which supports having a window in

which the user puts pixel data when raytracing.

 ;A-#5;/A(J'*/");% )9<% ;A-.J/A*); ñ the shader and texturing libraries for

the raytracer.

 ;A-J8= ñ a library that implements a remote procedure call (rpc)

mechanism. This library is a predecessor of the modern rpc system.

Unlike the typical UNIX rpc service, applications can set up services and

handle requests without requiring configuration by a system

administrator.

 ;A-"/% ñ the library that contains all of the geometry support, including

data representations for the primitives, support for raytracing (rt), and

binary I/O support for CSG geometric descriptions.

 ;A-U ñ a public-domain compression library.

 ;A-/*;, ;A-/8, and ;A-A/*; ñ libraries that provide the Tcl/Tk scripting

language.
4

 ;A-J9= ñ a library that provides portable network graphics (png).

6?2 F..;(%)9<%I/A;A/A'(

The application side of BRL-CAD also offers a number of tools and utilities.

They primarily concern (1) geometric conversion, (2) geometric interrogation,

(3) image format conversion, and (4) command-line-oriented image

manipulation. The following is a list of the major BRL-CAD tools and utilities.

 HTVQ (Multiple-Device Geometry Editor) ñ BRL-CADís graphics editor.

(For detailed guidance on the use of MGED as well as a list of all the

MGED commands currently available, see Butler et al. [2001].)

 Tools for raytracing and interrogating raytraced geometric objects.

"/ ñ the main raytracer for rendering images in BRL-CAD.

9A"/ ñ a package for firing rays interactively and getting information

about what the rays run into.

"'#"/ ñ a network-distributed raytracing package.

 An assortment of geometric converters to convert to and/or from other

geometry formats, including Euclid, ACAD, AutoCAD DXF, TANKILL,

Wavefront OBJ, Pro/ENGINEER, CATIA, JACK (the human factors

model for doing workload/usability studies), Viewpoint Data Lab,

NASTRAN, Digital Equipmentís Object File Format (OFF), Virtual

Reality Mark-up Language (VRML), Stereo Lithography (STL),

Cyberware Digitizer data, and FASTGEN4.

 -:A(+ ñ a Tcl/Tk interpreter in a windowing shell with enhancements

compiled into it for accessing BRL-CAD libraries. It also includes various

other extensions to the Tcl language.

 A"J"'J ñ produces input to the PRISM (Physically Realistic Infrared

Simulation Model) code.

 WXYV (Jonathanís Own Version of Emacs) ñ a fast, light implementation

of Emacs.

 Applications for displaying images of various types on the framebuffer

application and retrieving data from that framebuffer into images of

various types.

 Tools for generating geometry for common objects such as fences, walls,

and geometric mathematical oddities (e.g., the sphereflake shown in

Figure 2 in Section 4).
5

 Data manipulation programs to (1) convert integers to floats, floats to

doubles, etc. (e.g., *Z); (2) perform mathematical operations on file

elements (e.g., A#.<, 5#.<, and <#.<); (3) compute statistics of file

elements (e.g., A(/)/, 5(/)/, and <(/)/); etc.

 Utilities for building animation scripts ñ keeping track of columnar data

and interpolating it to allow one to produce input to the rt program to

render multiple items for animation.

 I/)+%&)(/'"%F..;%[A/ ñ image manipulation of all RLE-based images.

 Programs for manipulating images and converting between different

image file types. The two primary BRL-CAD types are JAO%(24-bit red,

green, and blue [RGB] color images) and -: (8-bit greyscale images).

Converters exist for various image formats including alias, png, ppm, etc.

 Programs for filtering images, doing histograms on the image data, and

extracting rectangles from the images.

 Tools for combining two images and blending them together. (These

tools were created before good image editing tools for video production

were available; today users would typically load the images directly into

a video editing package.)

3? @9(/);;)/A.9

3?2 X-/)A9A9=%/+'%B)*8)='

ARL currently offers two ways of obtaining the BRL-CAD package: (1) free

distribution, and (2) full-service distribution. In both cases, a limited license

agreement and survey (shown in the Appendix) must be signed by the user in

order to receive the binary (executable) and/or source code. This agreement can

be downloaded via anonymous file transfer protocol (FTP) from host

<ftp.arl.army.mil>, file /#*0&%12%3#''+'-.451$, or via hypertext transfer

protocol (http) from <http://ftp.arl.army.mil/brlcad/downloads/Current/

agreement.pdf> (U.S. Army Research Laboratory 2001).

Free distribution (without support) is available from the aforementioned FTP

site. Requests should be made to ARL at Aberdeen Proving Ground, MD, by

way of fax (410-278-9177) or postal mail (BRL-CAD Distribution, ATTN:

AMSRL-SL-B, APG, MD 21005-5068). After the license agreement is signed and

processed, download instructions and the decryption key are returned to the
6

requester. No further installation assistance or telephone assistance is available

under the free distribution method.

Full-service distribution is available for a fee (or free to Government agencies)

through the Aberdeen Satellite Office (ASO) of the Survivability Information

Analysis Center (SURVIAC), which provides training and administers

supported distributions and information exchange programs for ARL. The fullservice distribution includes installation support; maintenance release updates;

errata sheets; full technical support as needed via telephone, fax, e-mail, or

postal mail; and information about future BRL-CAD activities. Requests should

be made via telephone (410-273-7794), fax (410-272-6763), or postal mail (BRLCAD Distribution, SURVIAC ASO, 4695 Millennium Drive, Belcamp, MD 21017-

1505).

Any user who chooses the free distribution method to obtain BRL-CAD may

upgrade to the full-service distribution at any time. In addition, all users have

access to BRL-CAD symposia and workshops, the userís group, and the e-mail

list (<cad@arl.army.mil>). Requests to join the list or questions regarding the list

can be sent to <cad-request@arl.army.mil>.

3?6 1$(/'#%&'\5A"'#'9/(

Currently, BRL-CAD operates on a UNIX-based operating system and is

supported on FreeBSD, RedHat Linux, SGI Irix, and Sun Microsystems Solaris.

In addition, the package continues to be highly portable and has been run on

other platforms, including Alliant FX/8, FX/80, and FX/2800; Apple

Macintosh II running AUX; Convex C1; Cray-1,-2, X-MP, and Y-MP; Digital

Equipment VAX; Gould/Encore PN 6000/9000; IBM RS/6000; Pyramid 9820;

SGI 3030/Iris/Indigo/O2/Octane workstations; Sun-3 and Sun-4 SparcStation;

and VAX/VMS.

Porting to other UNIX-based systems is also easily accomplished, usually with a

day or two of effort. As of this writing, no port to Microsoft Windows has been

completed.

3?3 @"AO%L?O

The Irix binary distribution of BRL-CAD is intended for use on Irix 6.5. While

the distribution may also work on older versions of Irix, support is limited. The

ìIrix6.5 32-bit installation tardistî was built using SGIís -n32 compile option.

This package will work only on systems that have the -n32 libraries installed.

To install the file, perform the following steps:
7

]2^ Q.:9;.)<%4A;'

To download the 32-bit library version designed for Irix

6.5.distribution, shift-click on the link entitled ìIrix6.x 32-bit installation

tardist.î Save the file to your local machine.

]6^ Q'*"$J/%4A;'

Use the decryption key (which was provided to you after you signed

the license agreement) to decrypt the downloaded file. Type:

6,K.,!"#$%,8,/#*&%1!&#'()*+%9:#;<=>4.%#1;!.4K.,?

/#*&%1!&#'()*+%9:#;<=>4.%#1;!.

,-./01 1The terms ì!"#$%î and ì!&#'()*+%î throughout this document are

not to be typed literally. They are used simply as placeholders for the

appropriate decryption key value and BRL-CAD version number,

respectively, which should be typed in place of them. Note also that there

should be a space before and after ì!"#$%î but not ì!&#'()*+%î.

]3^ Y'"AM$%Q.:9;.)<_Q'*"$J/A.9

Now verify that the download and decryption were successful by

running the following:

6,+1>,/#*&%1!&#'()*+%@

Make sure that the resulting output matches that which is shown for

the appropriate version on the web site.

]D^ @9(/);;%B)*8)='

Either use the ìsuî(switch user) command or log in as ìroot.î

Remove any previous versions of BRL-CAD by typing the following:

A,;-!.

:-!.?,#'+)(',/#*&%1@4@

:-!.?,3)

:-!.?,B";.

Now install the new release with the following commands:

A,;-!.,0$,/#*&%1!&#'()*+%@4.%#1;!.

:-!.?,;-!.%**,@

:-!.?,3)

:-!.?,B";.
8

When ;-!. offers to save the distribution or remove it, select REMOVE.

The only things that will be removed are the temporary files that ;-!.

unpacked from the tardist file.

The complete BRL-CAD distribution is now installed in /usr/brlcad; just add

/usr/brlcad/bin to your search path, and you are ready to begin.

3?D 4"''E1Q

To install the package on a FreeBSD platform, perform the following steps:

]2^ Q.:9;.)<%4A;'

Download the encrypted package by going to <http://ftp.arl.army.mil

/brlcad/downloads/Current/freebsd.shtml> and shift-clicking on the

link in the left side bar entitled ìFreeBSD i86 package.î Save the file

(which is approximately 11 MB in size) to your local machine.

]6^ Y'"AM$%>"$J/%B".=")#

Verify that the crypt program is operating correctly by running the

following:

6,'&C),.'!.;-3,D,K.,30EFGH>=,D,)1,0&

The correct output is:

IIIIIII,,F>J,G>H,,,G,FIH,GG>,FHJ,GGG,F==

If instead you see the following:

IIIIIII,,,,C,FHF,IF>,FGJ,F=I,GG>,F>=,G>E

then you have the MD5 version of libcrypt, rather than the DES version,

installed. Alternatively, if you see the following:

IIIIIII,,,,;,FEE,GEH,GG=,,,K,F=>,,,L,,,M

then you have the correct version of libcrypt, but an older (broken)

FreeBSD variant of the crypt(3) library routine.
9

23&)+415'$6718'*9:#;(<

If you don't have the crypt command on your machine, or you get an error

message about ìmakekey,î or the test case doesn't decrypt, go to <http://ftp

.arl.army.mil/brlcad/downloads/Current/freebsd_crypt.shtml> and, using

the link on the left side bar, download the file K.9$#''/!14.%#43N. This tar file

contains an executable for the enigma program. Unpack it in the same

directory as the brlcad RPM file by running:

6,.%#,N<($,'-;3+%9$#''/!14.%#43N

Verify that the enigma program is operating correctly by running:

6,'&C),.'!.;-3,D,42'-;3+%,30EFGH>=,D,)1,0&

The correct output is:

OPQR:RST,UC%#%&.'#,V0V,;!,;**'3%*,;-,$;#!.,.W),/7.'!,)$,!%*.4

P..'+5.;-3,.),+%5,;-,/%&XW%#1!0&)+5%.;/*',+%--'#4

IIIIIII,,F>J,G>H,,,G,FIH,GG>,FHJ,GGG,F==

Now decrypt your BRL-CAD distribution with the following command:

6,42'-;3+%,!"#$%18,/#*&%10!&#'()*+%4.3N4K.,?,/#*&%10!&#'()*+%4.3N

This executable has the proper library routine already linked in and should

function regardless of the library installed in /usr/lib. Now go back to the

freebsd install page, verify the decryption, and continue the installation.

If the enigma program gives an error message or the md5 checksum of the

decrypted file isnít correct, you may have the MD5 version of

/usr/lib/libcrypt.* installed instead of the DES-compatible version. To test

this, type the following command into a shell window:

6,5'#*,0',V5#;-.,K.YZ3*)#5Z[Z3*Z\4,Z]-ZV

Now check the output. If it reads:

^E^3*^_>-4`R:a`SIXbW<O<Qc>FI

you have the MD5 crypt() library, which is incompatible. If it reads:

3*Ha!d+S(bea

you have the correct DES crypt() library.

R!&`@`TP% Be careful when correcting this problem. Installing the other

library may cause problems with your /etc/passwd passwords. Itís best to

compile enigma from the source code (from <http://ftp.arl.army.mil

/brlcad/downloads/Current/freebsd_crypt.shtml>) and forcibly link it

against the proper library. If you donít understand how to do this, contact

your system administrator for further assistance.
10

]3^ Q'*"$J/%4A;'

To decrypt the downloaded file, use the decryption key supplied to you

when your license agreement was processed. Use the following

command to decode the archive:

6,K.,!"#$%,8,/#*&%10!&#'()*+%4.3N4K.,?,/#*&%10!&#'()*+%4.3N

]D^ Y'"AM$%Q.:9;.)<_Q'*"$J/A.9

Run the following command to verify that the download and

decryption were successful:

6,+1>,/#*&%10!&#'()*+%4.3N@

Make sure that the resulting output matches what is shown for the

appropriate version on the web site.

]C^ @9(/);;%B)*8)='

Either use the ìsuî command or log in as ìroot.î

If you have installed a previous version of BRL-CAD, you will need to

uninstall it before installing the new version. To determine which

version of BRL-CAD is installed on your system, type the following

command:

5X39;-$),f%,D,'3#'5,g:-$)#+%.;)-,4@,/#*&%1h

If BRL-CAD is installed, the previous command should produce output

of the form:

:-$)#+%.;)-,$)#,/#*&%10!&#'()*+%

To remove this package from your system, type the following:

5X391'*'.',/#*&%10!&#'()*+%

To install the new version of BRL-CAD, run the following command:

A,5X39%11,/#*&%10!&#'()*+%4.3N
11

,-./01 If youíve not yet installed several optional system libraries, you

may see the following message:

5X39%11T,&)"*1,-).,$;-1,5%&X%3',5-30E4I4i,j

You can install the libraries via

A,5X39%11,ftp://ftp7.freebsd.org/pub/FreeBSD/FreeBSD-current/packages

/P**25-30E4I4i4.3N

Alternatively, you can build the libraries from source, as follows:

A,&1,2"!#25)#.!23#%5C;&!25-3k,+%X',;-!.%**

The complete BRL-CAD distribution is now installed in /usr/brlcad; just add

/usr/brlcad/bin to your search path, and you are ready to begin.

3?C ,A95O

To install BRL-CAD on a Linux i86 platform, perform the following steps:

]2^ Q.:9;.)<%4A;'

Download the encrypted package by going to the <http://ftp.arl.army

.mil/brlcad/downloads/Current/linux.shtml> web site and shiftclicking on the ìLinux RPMî link in the left side bar. Save the file

(which is approximately 12 MB in size) to your local machine.

]6^ Q'*"$J/%4A;'

To decrypt the downloaded file, use the decryption key that was

provided to you after your license agreement was processed. Use the

following command to decode the archive:

6, K., !"#$%, 8, /#*&%10!&#'()*+%0IGEG4;G_=4#5+4K., ?, /#*&%10!&#'()*+%0

IGEG4;G_=4#5+
12

23&)+415'$6718'*9:#;(<

If you don't have the crypt command on your machine, or you get an error

message about ìmakekey,î or the test case doesn't decrypt, go to <http://ftp

.arl.army.mil/brlcad/downloads/Current/linux_crypt.shtml> and download

the file K.9*;-"<4.%#43N using the link in the left side bar. This tar file

contains an executable for the enigma program. Unpack it in the same

directory as the brlcad RPM file by running the following:

6,.%#,N<($,'-;3+%9*;-"<4.%#43N

Verify that the enigma program is operating correctly by running the

following:

6,'&C),.'!.;-3,D,42'-;3+%,30EFGH>=,D,)1,0&

The correct output is:

IIIIIII,,F>J,G>H,,,G,FIH,GG>,FHJ,GGG,F==

Now decrypt your BRL-CAD distribution with the following command:

6,42'-;3+%,!"#$%,8,/#*&%10!&#'()*+%0IGIF4;G_=4#5+4K.,?

/#*&%10!&#'()*+%0IGIF4;G_=4#5+

This executable has the proper library routine already linked in; it should

function correctly regardless of which library you have installed in /usr/lib.

Now go back to the Linux install page to verify the decryption.

If the enigma program gives you an error message or the md5 checksum of

the decrypted file is not correct, you may have the MD5 version of

/usr/lib/libcrypt.* installed instead of the DES-compatible version. To test

this, type the following command into a shell window:

6,5'#*,0',V5#;-.,K.YZ3*)#5Z[Z3*Z\4,Z]-ZV

Check the output in the following table. If it reads

^E^3*^_>-4`R:a`SIXbW<O<Qc>FI

you have the MD5 crypt() library, which is incompatible. If it reads

3*Ha!d+S(bea

you have the correct DES crypt() library.

R!&`@`TP% Be careful when correcting this problem because installing the

other library may cause problems with your /etc/passwd passwords. Itís

best to compile enigma from the source code (from <http://ftp.arl.army.mil

/brlcad/downloads/Current/linux_crypt.shtml>) and forcibly link it against

the proper library. If you donít know how to do this, contact your system

administrator for further assistance.
13

]3^ Y'"AM$%Q.:9;.)<_Q'*"$J/A.9

Verify that the download and decryption were successful by running

the following:

6,+1>!"+,/#*&%10!&#'()*+%@

Make sure that the resulting output matches that shown for the

appropriate version on the web site.

]D^ @9(/);;%B)*8)='

Either use the ìsuî command or log in as ìroot.î

Run the following command:

A,#5+,0;C(,/#*&%10!&#'()*+%0IGEG4;G_=4#5+

If you have installed a previous version of BRL-CAD, you will need to

specify ìupgradeî rather than ìinstall.î You can do this with the

following command:

A,#5+,0lC(,/#*&%10!&#'()*+%0IGEG4;G_=4#5+

If you have an old non-RPM BRL-CAD in /usr/brlcad, do an "rm -rf

/usr/brlcad" as root before starting the installation.

The complete BRL-CAD distribution is installed in /usr/brlcad; just add

/usr/brlcad/bin to your search path, and you are ready to begin.

3?L 1.;)"A(

To install BRL-CAD on a Solaris SPARC platform, perform the following steps:

]2^ Q.:9;.)<%4A;'

Download the encrypted package by going to the <http://ftp.arl

.army.mil/brlcad/downloads/Current/solaris.shtml> web site and

shift-clicking on the link entitled ìSolaris packageî on the left side bar.

Save the file (which is approximately 20 MB in size) to your local

machine.

]6^ Y'"AM$%>"$J/%B".=")#

Verify that the crypt program is operating correctly by running the

following:

6,'&C),.'!.;-3,D,K.,30EFGH>=,D,)1,0&

The correct output is:

IIIIIII,,F>J,G>H,,,G,FIH,GG>,FHJ,GGG,F==

IIIIIEI
14

]3^ Q'*"$J/%4A;'

To decrypt the downloaded file, use the decryption key that was

supplied to you after your licensing agreement was processed. Use the

following command to decode the archive:

6, K., !"#$%, 8, /#*&%10!&#'()*+%0FIIE4IG4EG0!)*%#;!43N4K., D, 3"-N;5, ?

/#*&%10!&#'()*+%0FIIE4IG4EG0!)*%#;!

]D^ Y'"AM$%Q.:9;.)<_Q'*"$J/A.9

Verify that the download and decryption were successful by running

the following:

6,+1>,/#*&%10!&#'()*+%0@!)*%#;!@

Make sure that the resulting output matches that shown for the

appropriate version on the web site.

]C^ @9(/);;%B)*8)='

Either use the ìsuî command or log in as ìroot.î

If you have installed a previous version of BRL-CAD, you will need to

uninstall it before installing the new version. To do this, run the

following command:

A,5X3#+,/#*&%1

To install the new version of BRL-CAD, run the following command:

A,5X3%11,/#*&%10!&#'()*+%0FIIE4IG4EG0!)*%#;!

The complete BRL-CAD distribution is now installed in /usr/brlcad; just add

/usr/brlcad/bin to your search path, and you are ready to begin.

3?G 1.5"*'%>.<'

Performing an installation from source involves more effort than a binary

distribution. Users are encouraged to install the appropriate binary distribution

whenever possible. However, for special requirements or for systems in which a

binary distribution is not available, the source distribution is the only way to

proceed. To install from source, perform the following steps:

]2^ Q.:9;.)<%4A;'

Download the encrypted file by going to the <http://ftp.arl.

army.mil/brlcad/downloads/Current/src.shtml> web site and shiftclicking on link entitled "Source archive" on the left side bar. Save the

gzipped ìtarî file (which is approximately 17 MB in size) to your local

machine somewhere other than the directory where you intend to

install the BRL-CAD products.
15

,-./0 If you have problems downloading this large file, you can

download each file individually by selecting them, in turn, under the

ìSmaller Downloadsî links on the left side bar of the <http://ftp.arl

.army.mil/brlcad/downloads/Current/src.shtml> web site.

]6^ Y'"AM$%Q.:9;.)<

To verify that the download was successful on each file, run the

following command(s) (On a Linux platform, you may need to run

md5sum instead.):

6,+1>,&%1!&#'()*+%4.%#43N4K.

or

6,+1>,&%1!&#'()*+%4.%#0m43N4K.

]3^ Q'*"$J/%4A;'

To decrypt the downloaded file, use the decryption key provided to

you after processing of your license agreement (or after receiving a

prior release). Use the following command to decode the archive:

6,K.,!"#$%,8,&%1!&#'()*+%4.%#43N4K.,?,&%1>4G4.%#43N

If you downloaded the smaller files instead, you must do this to each

file, in turn, as follows:

6,K.,!"#$%,8,&%1!&#'()*+%4.%#0%43N4K.,?,&%1!&#'()*+%4.%#0%4.%#43N

6,K.,!"#$%,8,&%1!&#'()*+%4.%#0/43N4K.,?,&%1!&#'()*+%4.%#0/4.%#43N

etc.

]D^ I9*.#J"'((_I9J)*8%!"*+AZ'

If you downloaded the entire file at once, run the following command:

6,3"-N;5,8,&%1!&#'()*+%4.%#43N,D,.%#,<$,f

If you downloaded the smaller files instead, run the following

command for each file, in turn:

6,3"-N;5,8,&%1!&#'()*+%4.%#0%4.%#43N,D,.%#,<$,0

6,3"-N;5,8,&%1!&#'()*+%4.%#0/4.%#43N,D,.%#,<$,f

etc.

Be sure the destination directory for the installation exists. Type

6,+X1;#,2"!#2/#*&%1
16

If you choose a directory other than /usr/brlcad, you will need to set

the environment variable BRLCAD_ROOT to be the name of this

directory.

A number of directories are created under the root directory for the

software package. The full names of these are compiled into various

parts of BRL-CAD. As a result, it is not possible to compile the package

for one location and later relocate the binaries to another.

Be sure that /usr/brlcad/bin or $BRLCAD_ROOT/bin is in your shell

path as follows. For /bin/sh:

nQoUPp9Qccqr2"!#2/#*&%1

sPqLr^sPqLT2"!#2/#*&%12/;-

'<5)#.,sPqL

Likewise, for csh:

!'.'-(,nQoUPp9Qccq,2"!#2/#*&%1

!'.,5%.CrY^5%.C,2"!#2/#*&%12/;-\

]C^ >.#JA;'%B)*8)='

Now compile the package as follows:

6,&1,/#*&%1

6,!C,!'."54!C

The next step can take a considerable amount of time on some systems.

For sh, type the following:

6,+%X',?,+%X'4*)3,F?E

For csh, type the following:

6,+%X',?t,+%X'4*)3

]L^ @9(/);;%B)*8)='

Before installing the package, review the log of compilation for errors.

If there are no errors, then type the following:

6,+%X',;-!.%**

The complete BRL-CAD distribution is now installed in /usr/brlcad; just add

/usr/brlcad/bin to your search path, and you are ready to begin.
17

D? E'9*+#)"8%F'(/A9=

As changes are implemented in BRL-CAD, ARL developers run a standard set of

computationally intensive image files (shown in Figure 2) on a common machine

in order to benchmark and compare raytrace performance. In addition, these

images are provided with each source distribution of the package so that users

can also test performance on their machines, if desired.

To run the benchmark images, run the script #"-4!C in the ìbenchî directory of

the source directory tree.

Moss World Star

Bldg 391 M35 Sphflake

Figure 2. Benchmarking images.
18

C? H)A9/'9)9*'%)9<%IJ<)/'(

C?2 F".5-;'(+../A9=%)9<%F")*8A9=%E5=(

When a bug or deficiency is found in BRL-CAD, the user should report the

problem to ARL developers as soon as possible. This is easily accomplished by

filing a Bug Report via the shell script &%10/"34!C (which is provided with each

distribution of the package). In order to process the bug quickly and efficiently,

the following information should be included in the Bug Report:

 !-(/")*/%ñ a short (40 characters or fewer) tag line indicating the name of

library and the problem/deficiency (e.g., Bug in MGED when Raytracing

Spheres).

 V9ZA".9#'9/%ñ which version of BRL-CAD is being used, the hardware

on which it is being used, and the operating system.

 &'J')/0E$ ñ the sequence of procedures that preceded/caused the

problem.

 Q'(*"AJ/A.9 ñ a detailed summary of the problem or suggestion.

 4AO ñ proposed solutions (if any) for fixing the problem/deficiency.

BRL-CAD bugs are filed into one of three categories in the Bug Report Registry:

New, Pending, and Closed. When notice of a bug is received, the report is filed

in the New directory. Due to regulations regarding the content of Army web

sites, new messages are not immediately made available to the public.

After a BRL-CAD developer has verified that a new Bug Report is valid, the

aforementioned script message is automatically converted to HTML format and

placed into the Pending directory, which is publicly visible. The status of the

message is then continuously updated by developers as they work to solve the

problem.

Finally, when the fix has been satisfactorily addressed (as determined by the

BRL-CAD developer), the report and all of its amendments are moved to the

Closed directory, where they remain in a publicly viewable archive.

C?6 `':%&';')('(

As new versions of BRL-CAD are released, announcements and release notes are

made through the <cad@arl.army.mil> list. Interested users can then download

the encrypted files from the Internet and decrypt them using their original

decryption key.
19

L? &'M'"'9*'(

Butler, Lee A., Eric W. Edwards, Betty J. Schueler, Robert G. Parker, and John R.

Anderson. ìBRL-CAD Tutorial Series: Volume II - Introduction to MGED.î

ARL-SR-102, U.S. Army Research Laboratory, Aberdeen Proving Ground,

MD, April 2001.

U.S. Army Research Laboratory. <http://ftp.arl.army.mil/brlcad/> and

subpages, Aberdeen Proving Ground, June 2001.
20

INTENTIONALLY LEFT BLANK.
21

!JJ'9<AOP%%E&,0>!Q%,A*'9('%!="''#'9/
22
23
24
25
26

INTENTIONALLY LEFT BLANK.
27

NO. OF

COPIES ORGANIZATION

1 DEFENSE TECHNICAL

INFORMATION CENTER

DTIC OCA

8725 JOHN J KINGMAN RD

STE 0944

FT BELVOIR VA 22060-6218

1 DIRECTOR

US ARMY RESEARCH LAB

AMSRL D

R W WHALIN

2800 POWDER MILL RD

ADELPHI MD 20783-1197

1 DIRECTOR

US ARMY RESEARCH LAB

AMSRL D

D SMITH

2800 POWDER MILL RD

ADELPHI MD 20783-1197

3 DIRECTOR

US ARMY RESEARCH LAB

AMSRL CI LL

2800 POWDER MILL RD

ADELPHI MD 20783-1197

1 DIRECTOR

US ARMY RESEARCH LAB

AMSRL CI AI R

2800 POWDER MILL RD

ADELPHI MD 20783-1197

1 DIRECTOR

US ARMY RESEARCH LAB

AMSRL CI AP

2800 POWDER MILL RD

ADELPHI MD 20783-1197

1 DIRECTOR

US ARMY RESEARCH LAB

AMSRL SL

C HOPPER

WSMR NM 88002-5513

1 NAWC

WEAPONS DIVISION

CODE 418300D A WEARNER

BLDG 91073

1 ADMINISTRATION CIRCLE

CHINA LAKE CA 93555-6100

NO. OF

COPIES ORGANIZATION

1 AIR FORCE ARMAMENT CNTR

AAC/ENMA

D MCCOWN

101 W EGLIN BLVD

EGLIN AFB FL 32542-5549

1 USAF

46 OG OGMLV

B THORN

104 CHEROKEE AVE

EGLIN AFB FL 32542-5600

1 USAF WRIGHT LABORATORY

46TH OG OGM AL AC

M LENTZ

2700 D STREET BLDG 22B

WRIGHT PAT AFB OH

45433-7605

1 SURVIAC

ABERDEEN SATELLITE OFC

A LAGRANGE

4695 MILLENNIUM DRIVE

BELCAMP MD 21017-1505

6 THE SURVICE ENGNRG CO

D KREGEL

B STRAUSSER

C BOYER

M HARDIN

M BUTKIEWICZ

L MCKAY

4695 MILLENNIUM DRIVE

BELCAMP MD 21017-1505

ABERDEEN PROVING GROUND

4 DIR USARL

AMSRL CI LP (305)

220 DIR AMSRL

AMSRL SL

DR WADE

J BEILFUSS

AMSRL SL E

M STARKS

AMSRL SL EC

E PANUSKA

AMSRL SL EM

J FEENEY
28

NO. OF

COPIES ORGANIZATION

AMSRL SL B (5 CPS)

AMSRL SL BA (25 CPS)

AMSRL SL BD (15 CPS)

AMSRL SL BE (25 CPS)

L BUTLER (100 CPS)

AMSRL SL BG (25 CPS)

AMSRL SL BN (20 CPS)
29
30

INTENTIONALLY LEFT BLANK.