BURST(1)

The units command will set the linear units for input and output. This command should be used before any scalar quantities such as coordinates, distances, or sizes are input. The units may be changed to accommodate input files of differing units, but the output from a particular run will reflect whatever the units were set to when the execute command was given. One argument is expected out of the following list and must be spelled correctly: millimeters, centimeters, meters, inches and feet. The default units are millimeters.

Note that when specifying angles as options to commands angles are always expressed in degrees, not radians.

It is considered an error if two regions in a BRL-CAD .g file occupy the same space; we call this an overlap. The ray tracing library (librt) will report overlapping regions that are intersected by shotlines or burst rays to the burst application and the program will, by default, print out any that have a line of sight thickness of at least 0.25 millimeters (see Error Log). Although a target may only have a small number of overlapping regions, an error will be reported for each ray that intersects one of them. Generally this results in the messages being repetitious. Although these diagnostics are important for fixing problems in the geometric description of the target, the user may wish to proceed with a production run and the printing of these errors can slow the execution time considerably. A yes or no argument to the report-overlaps command will turn the diagnostics on or off. Regardless of whether or not individual overlaps are reported, the total number detected will be logged.

When overlap reporting is enabled, the full path name of both regions is printed as seen in the following example:

The zero enclosed in double curly brackets is intended to discriminate between instances. Theoretically, isol and osol are the names of the starting and ending solids associated with the boolean operations on the overlapping partition. In practice these solid names are typically not helpful in diagnosing the problem, but the region names should be sufficient. The depth is the line-of-sight thickness of the overlapping partition in millimeters. In parentheses, are printed the target coordinates of the intersection of the ray with the overlap. The x-2 and y1 reveal that the grid indices of the shotline are -2, 1; this means that the shotline was 2 cells to the left, and one cell above the grid origin. If lvl (meaning ray tracing recursion level) is zero, then the overlap resulted from a shotline, but if it is one, it could represent either a burst ray intersection or a probe to calculate the normal thickness of a component intersected by the shotline. The real purpose of the ray is stated last.

The orientation of shotlines with respect to the coordinate system of the target are described by azimuth and elevation angles. These angles must be specified in degrees as floating-point numbers via the attack-direction.

An envelope refers to a grid that is dimensioned such that its rectangular area, projected normal to the grid, will cover optionally all or part of the target. The enclose-target option will generate a grid that is guaranteed to cover the entire target. Since BRL-CAD uses combinatorial solid geometry as one of its shape representation methods, the dimensions of the target are not known in advance. Therefore, a worst case bounding rectangular parallel piped (RPP) is used to generate the grid and the grid may be larger than necessary. In addition, depending on the attack aspect, the presented area of some targets may not fill up a rectangular grid well. This should not be a problem since ray tracing outside the target boundaries is cheap, but if desired the grid can be trimmed down with the partial envelope option enclose-portion. The grid origin is always aligned with the target origin.

The enclose-portion option allows the user to generate a sub-grid by specifying the distances from the grid origin to the sub-grid’s left, right, top, and bottom boundaries.

The dimensions of a grid cell are input as floating-point values that represent the distances between the centers of adjacent cells. cell-size also expresses the projected area of influence associated with a shotline or burst ray. Therefore, cell-size must be specified even when a grid will not be generated, such as with discrete shot or discrete burst point selection (see Input Discrete Shots and Input Discrete Burst Points).

When gridding, shotlines normally pass through the center of each cell, however, they may be also be dithered via the dither-cells command. If the user chooses the latter, 2 random numbers are selected for each cell that are used to offset the shotline in both parametric directions of the grid plane, but within the respective cell’s boundaries.

If the user wants to fire at a known point on the target, he or she may wish to describe the shotline location in target coordinates. When coupled with the attack direction, each 3-dimensional coordinate uniquely specifies a shotline. The input-3d-shot command allows the user to type in a single shot location as an X, Y, and Z coordinate that is run when the execute command is given, but remember that no queueing of shots occurs in this mode; the last set of coordinates entered will be used. For inputing multiple shots, read-3d-shot-file can be used to loop through every set of target coordinates in the named file after the execute command is run. The file should contain three floating-point numbers on each line separated by white space (blanks or tabs).

Another way to describe a shot location is in the shotline coordinate system. Since the X' location of the shot is irrelevant (the shotline is parallel to the X' axis) a shot may be specified as a Y' and Z' coordinate. These coordinates can also be referred to as horizontal and vertical grid offsets. The input-2d-shot option allows the user to type in a single shot location as a Y', and Z' coordinate which will be run when the execute command is given, but like the 3d case no queueing of shots occurs in this mode and only the last set of grid offsets entered will be used. To input multiple shots, the read-2d-shot-file can be used; execute will loop through every set of grid offsets in the named file. The file should contain three floating-point numbers on each line separated by white space (blanks or tabs).

Depending on threat type, burst points may be located using two basic techniques. The first technique is simply to input the burst point coordinates. This method can be used to compare vulnerability analysis results with empirical results from the firing range or combat field. The second technique available to the user is to burst along a shotline. This option is used more for predicting the burst point location based on target geometry, given certain parameters that describe the target/threat interactions.

The following parameters influence both the triggering mechanism for burst points, as well as the characteristics of the cone of rays generated from each point.

This group of commands is for specification of target-specific input files.

The burst-file command will open the named file for creating a burst point library. If the file exists, it will be truncated by this command.

The shotline-file command will open the named file for creating a shotline file. If the file exists, it will be truncated by this command.

The plot-file command generates a plot file, using BRL-CAD extensions to the standard format. This option is useful for examining the shotline and burst ray information graphically as a three-dimensional vector plot. Due to constraints inherent in the plot format, these plots must be displayed as a post-process step by using a BRL-CAD plotting utility such as pl-fb. Because some of these display programs do not support multiple plots per file, the file name should be changed between runs. The following table describes the color mapping associated with these plots:

If the user has specified a color mapping file with the color-file command, then those colors will be used rather than the above colors for all shotline/ray intersections.

The image-file command will generate a color image that provides the user with immediate feedback about a run. The grid is displayed graphically and each cell location is dynamically color coded to show its current status. The following table describes the color mapping associated with the grid:

In addition to the above cell colors, hits on critical components by burst rays are depicted as a colored pixel projected into grid space from the intersection point where the ray enters the component. Colors for the components are mapped from ident numbers according to the table specified by the user with the color-file command and shaded using a lighting model illuminated from the viewing direction.

The grid-file command will store each shotline coordinate generated during the run as grid offsets. These files can later be read in to replicate a previous run’s grid or discrete shots by using the read-2d-shot-file command. This capability is especially useful when dithered shotlines have been used and it is desired that the same shotlines be used in another run. Note that the shotline intersection information is not saved, just the grid offsets for each shotline.

During a session, all commands are saved in a temporary file. The write-input-file command will create a snapshot of this session file, that can later be used to recreate the current session up to the point when the file was written. The session or input files can later be used in one of two ways: either read in with the read-input-file command, or supplied on the standard input of the burst program. Note that the write-input-file and read-input-file commands will not be included in the input files, but the commands read in by the latter will.

The error-file command is useful to save errors in a log file and prevent copious ray tracer diagnostics from scrolling by on the screen. This option is especially useful if using the batch mode of execution so that the terminal is not tied up by program output. If no error log is specified, diagnostic messages will appear in the scrolling window or, if in batch mode, on the burst program’s standard error output.

The histogram-file command generates a frequency histogram to the named file. The file format is simply one number per line; each number is a count of critical components hit by an individual burst ray. This file can easily be post-processed to display a histogram, for instance, how many rays hit zero, one, two, three, etc. components.