burst uses LIBRT raytracing to prepare inputs to the Point Burst Damage Assessment Model (PDAM) in the form of shotline files and burst point library files. For more information about PDAM, see ARL-CR-69: A Guide to FASTGEN Target Geometric Modeling.
The burst program is designed to allow many options to be
configured before any outputs are calculated. Unless otherwise stated in the
individual command descriptions, a given command will nullify any previous
occurrence of the same directive until an execute command
is given. For instance, the command target-file
tank1 followed by
target-file tank2 will
nullify the reference to tank1. It is also important to remember that the
units command impacts how subsequent physical quantities
are read by other commands, and the output from an execute
command will use whatever units are current. Once the input parameters are specified,
the execute command will start a run. Output will be
reported using the current setting for units at the
time the execute is run. Many runs may occur during an instance of
the burst program. One such instance is referred to as a session.
Commands are defined via an input file and passed to burst when it is first invoked. All commands to burst are composed of one or more words connected by hyphens and each command may require one or more arguments that must be separated by either spaces or tabs. A line that begins with the ‘#’ symbol is considered a comment and will be ignored. The following table provides a brief overview of the available commands, with subsequent sections covering key areas in more detail. In the table, flag arguments have yes or no values, an angle is expressed in degrees as a floating-point quantity, distances and coordinates such as X, Y, Z, left, right, etc. are also floating-point numbers, and count represents an integer. Square brackets delimit optional arguments.
Table 1. Burst Commands
| Command | Arguments | Description |
|---|---|---|
| attack-direction | azim_angle elev_angle | specify azimuth and elevation of attack relative to target |
| burst-air-file | file | input burst air idents from file |
| burst-armor-file | file | input burst armor idents from file |
| burst-coordinates | X Y Z | input single burst point location in target coordinates |
| burst-distance | distance | offset burst point along shotline |
| burst-file | file | output burst point library to file |
| cell-size | distance | specify shotline separation (equidistant horizontal and vertical) |
| color-file | file | input ident to color mapping from file (for graphics) |
| cone-half-angle | angle | specify limiting angle for spall ray generation |
| critical-comp-file | file | input critical component idents from file |
| deflect-spall-cone | flag | deflect axis of spall cone half way towards exit normal |
| dither-cells | flag | if yes, randomly offset shotline within grid cell |
| enclose-target | generate rectangular grid of shotlines for full target envelope | |
| enclose-portion | left right bottom top | generate partial envelope by specifying grid boundaries |
| error-file | file | divert all diagnostics to file |
| execute | initiate a run (no output produced without this command) | |
| grid-file | file | save shotline locations (Y' Z') in file |
| ground-plane | flag [Z +X -X +Y -Y] | if yes, burst on ground |
| help | display a list of available commands | |
| histogram-file | file | write hit frequency histogram to file |
| image-file | file | generate frame buffer image on a specified file or device |
| input-2d-shot | Y' Z' | input single shotline location as grid offsets |
| input-3d-shot | X Y Z | input single shotline location in target coordinates |
| max-barriers | count | specify the maximum number of components to report along spall ray |
| max-spall-rays | count | specify the desired number of spall rays generated per burst point |
| plot-file | file | generate plot data in file |
| quit | quit the application | |
| read-2d-shot-file | file | read shot locations from file as grid offsets (see input-2d-shot) |
| read-3d-shot-file | file | read shot locations from file in target coordinates (see input-3d-shot) |
| read-burst-file | file | read burst point locations from file (see burst-coordinates) |
| read-input-file | file | read key word commands from file |
| report-overlaps | flag | if yes, log overlap diagnostics |
| shotline-burst | flag | if yes, generate burst points along shotlines |
| shotline-file | file | output shot line data to file |
| target-file | file | read BRL-CAD database from file |
| target-objects | object0 [object1 object2 ...] | list objects from BRL-CAD database to interrogate |
| units | name | linear units (inches, feet, millimeters, centimeters,meters) |
| write-input-file | file | save script of commands in file |
| # | any line beginning with the '#' character is a comment |
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:
OVERLAP:
reg=/component/turret/tur.ext/tur.armor/tur.bot{{0}} isol=s2,
reg=/component/hull/hull.ext/hull.armor/r1.top{{0}} osol=ss4,
depth 544.21mm at (-471.784,812.8,0) x-2 y1 lvl0 purpose=shotline
OVERLAP:
reg=/component/turret/tur.ext/tur.ring{{0}} isol=ss2,
reg=/component/turret/tur.ext/tur.armor/tur.bot{{0}} osol=s2,
depth 25.39mm at (-418.907,812.8,0) x-2 y1 lvl1 purpose=normal thickness
OVERLAP:
reg=/component/turret/tur.ext/tur.ring{{0}} isol=ss2,
reg=/component/turret/tur.ext/tur.armor/tur.bot{{0}} osol=s2,
depth 52.88mm at (-418.907,-812.8,0) x-2 y1 lvl1 purpose=spall ray
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.
Shotlining is a technique whereby lines are described in the target coordinate system and information is requested about the geometry that intersects those lines in 3-space. This technique is useful for analysis programs that must simulate threat/target interactions, and therefore must sample the geometry along the threat path. Typically the lines are specified discretely, by a point and a direction, or a grid of lines is generated that is oriented perpendicular to the direction of attack. A grid is rectangular, but is subdivided along its height and width uniformly resulting in square cells. Gridding techniques include passing a line called a shotline through the center of each cell, or alternatively, dithering each shotline’s position within its respective cell’s boundaries (see Dithering Shotlines).
The user is faced with several choices for generating shotlines; full-target envelope, partial envelopes, or discrete shots. No matter what shotlining method is used, a grid always exists as a frame of reference for specifying 2-dimensional coordinates in the plane normal to the direction of attack. This 2-dimensional coordinate system is a projection of the shotline coordinate system (also referred to as the primed coordinate system). For the simple case of a zero azimuth, zero elevation attack, the X’, Y’, and Z’ axes in the shotline coordinate system coincide with the X, Y, and Z axes of the target coordinate system and the shotline direction is parallel to the X’ axis and headed toward decreasing coordinates. Other orientations are described by rotating the X’, Y’, and Z’ axes to keep the shotline direction always down the X’ axis. This transformation involves two rotations; first a rotation of the primed coordinate system about the coincident Z and Z’ axes by the specified azimuthal angle, followed by a rotation about the new Y’ axis by the specified elevation angle. Since the grid is a 2-d projection of the shotline coordinate system, it has no X coordinate; if the user’s viewpoint is from the direction of attack, the Y’ axis can be thought of as horizontal with increasing coordinates to the right, and the Z’ axis as vertical and increasing in the upward direction.
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).
Bursting is a technique for sampling a target’s geometry with the use of ray tracing. As opposed to shotlining involving parallel rays, bursting employs a distribution of rays that emanate from a single point. The burst program generates rays that approximate a uniform distribution over a user-specified solid angle (see Sampling Cone Half Angle) and having a density (see Number of Sampling Rays) that is also under control of the user. The user also has a choice between several mechanisms for setting up burst point locations depending on the particular threat he is attempting to emulate.
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 input of explicit burst point coordinates can be accomplished either by typing them in one at a time or by reading a file of target X, Y, and Z coordinates.
The burst-coordinates command allows the user to type in a single burst point location as an X, Y, and Z coordinate. When the execute command is given, that one burst point will be run. No queueing of burst points occurs in this mode, the last set of coordinates entered will be used.
The read-burst-file command allows the user to specify a number of burst points from a file; this option will, after submission of an execute directive, loop through every set of target coordinates in the named file. The file should contain three numbers on each line separated by white space (blanks or tabs).
The shotline-burst command can be given a yes or no argument to either enable or disable this method of generating burst points. When a yes argument is given, a second yes or no argument is also required (see Burst on Armor). Bursting along a shotline can be done different ways depending on the combination of several options. The location of the burst point is based on the triggering mechanism that is selected with the burst distance parameter.
If the burst-distance paramter is set to a negative or zero value, then interior burst points will be generated (see Burst Distance). This method of bursting requires the input of burst armor idents and, by default, burst air idents are also required. If the user does not want to require that certain air be present to trigger a burst point, the shotline-burst command has a second argument. When this second argument is set to no, bursting will occur as long as burst armor is followed by any air or void (empty space), and the burst air file is not required. For more information see Burst Armor and Burst Air Ident Files.
Ground plane bursting is a vehicle for evaluating the effect of fragmenting warheads on light-armored vehicles when they strike the ground in close proximity to the target. The ground-plane command is only relevant when bursting along a shotline is selected. The ground is modeled as a rectangle lying in a plane parallel to the target X-Y plane with edges parallel to the X and Y axes. The grid will be enlarged to include the ground plane; it is important for efficiency to limit the size of the ground plane to match the range of the fragments that may be generated by the particular threat being modeled. When enabling this option, the ground-plane command is given a yes argument followed by the height of the target above the ground, and the distances that the ground rectangle extends out positive X, negative X, positive Y, and negative Y axes.
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.
The burst-distance parameter is modeled after the BDIST parameter used by the Air Force’s PGEN code. The role of this parameter is overloaded, however it was retained to aid PGEN users in transitioning to the burst program. If it is zero or negative, then interior bursting is enabled, otherwise, if it is greater than zero, exterior bursting will occur, subject to certain conditions (see below). The magnitude of this parameter is used to offset the burst point location along the shotline relative to the geometry that triggered the burst.
Burst armor refers to a component whose ident code is found in the list input by the burst-armor-file command. Similarly, burst air refers to a component whose ident code is found in the list input by the burst-air-file directive. If interior bursting is enabled and a burst armor component is encountered along a shotline that is immediately followed by burst air, then a burst point will be located the absolute value of burst distance beyond the exit of the shotline from the component. This means that if burst distance is zero, the burst point will lie at the burst armor/air interface, and if it’s -5.5, the burst point will lie 5.5 units inside the air compartment from the back surface of the armor.
If burst distance is greater than zero, the first component encountered along the shotline will trigger a burst point, regardless of its ident code, that will be located burst distance in front of the shotline entry point. This technique simulates the behavior of a fragmenting munition with a standoff fuzing such that detonation is triggered before the collision of the warhead with the target. The burst distance is set to imitate the built in standoff of the warhead. When employing exterior bursting methods, burst armor and burst air are not used.
To limit the solid angle within which burst rays will be generated, the user may specify a cone half angle. This angle represents the degrees (in floating point) from the axis of the cone to its limiting surface. The default value for the cone half angle is 45 degrees.
The spall cone axis is, by default, aligned with the shotline. In reality, the center of mass of the spall cloud would be between the shotline direction and the exit normal of the shotline from the spalling component. By aligning the spall cone axis with a vector halfway between the shotline and the exit normal, a narrower cone half angle can be used and still sample within the solid angle of interest. This technique can therefore be used to cut down on the number of rays calculated without lowering the sampling density. The deflect-spall-cone command takes a yes or no argument about whether or not to divert the cone axis.
The sampling ray density within the spall cone is controlled by specifying the maximum number of rays desired with the max-spall-rays command. Due to the uniform distribution algorithm employed, the number of rays calculated will be slightly less.
For munitions known to have limited penetration capability, the user may set a limit on the number of burst ray intersections reported with the max-barriers command. The effect of setting this parameter is to reduce the size of the burst point library (see Burst Point Library) by limiting the number of components that will be reported per burst ray. By default, up to 100 components are reported, as it is not expected that this number will be reached under normal circumstances.
This group of commands is for specification of target-specific input files.
The input of the target’s BRL-CAD .g file is accomplished with the target-file command. Note that only one data base may be read in during a given session. If the user wishes to change the target once the execute command has been given, they must exit the burst program and start a new session.
After specifying the BRL-CAD .g file, the user must list all of the objects in the .g hierarchy that they wish to include in the analysis with the target-objects command. The objects must be listed as arguments to one target-objects command with spaces or tabs as separators. Note that only one list of objects may be loaded per session, however, they do not get loaded until the execute command is given.
Idents refer to the region ident code from the BRL-CAD .g file. Lists of idents may be specified singly or as ranges. Individual idents must appear as one per line, but ranges are specified by two numbers on a line that are separated by one or more of the following characters: comma, hyphen, colon, semicolon, space, or tab. For example:
600-999 1011 4002-4050 8000 9001 9004 9005
When interior burst points are to be generated along a shotline (see Interior Bursting) a file of burst armor idents must be specified with the burst-armor-file command. Additionally a burst air idents file must be specified with the burst-air-file command. If a shotline intersects a component whose ident has been input as a burst armor and it is immediately followed by burst air a burst point will be triggered.
Whether interior or exterior bursting is being employed, information about components hit by burst rays will only be output for rays that hit critical components. The file name containing a list of critical component idents must therefore be specified by the critical-comp-file command if burst points are to be generated.
The color-file command allows users to assign colors to component idents for graphics options, in particular, the image-file and plot-file commands. The format of this file is 5 numbers per line separated by blanks or tabs. The first number is the low end of an ident range and the second number is the high end of the range (both numbers are inclusive). This range is mapped to the color specified by the last 3 numbers on the line that are red, green, and blue components of the color (values for these components must be between 0 and 255 inclusive). For example:
4001 4003 255 255 0 # Fuel 4050 4050 255 255 0 # Fuel 8000 8001 255 100 255 # Ammo 100 165 150 255 100 # Hull armor 610 619 220 150 100 # Commander 720 729 220 150 100 # Gunner 830 839 220 150 100 # Loader 940 949 220 150 100 # Driver
The read-input-file command reads an input file of commands. These files can be generated manually by using a text editor or saved from a session file with the write-input-file command. See Command Input for the format of this file.
For an explanation of commands for reading in files of shotline or burst point coordinates, see Input Discrete Shots and Input Discrete Burst Points.
The following commands will turn on optional output. By default, no output is produced except error logging (see Error Log), unless an output file is specified with the appropriate command. Any combination of output options may be specified for a particular run. Note that specifying an output file will cause an existing file with that name to be truncated to zero length. Therefore, only one such command should be entered per session for a particular file name. Multiple runs during a session will append to the same files if intervening commands to change the output file name are not given, except for the graphics files as explained below. Note that there is no way to append to a file created by a previous session of the burst program, but these files may be concatenated after the fact.
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:
Table 2. Color Key for Plots
| Color | R | G | B | Representation |
|---|---|---|---|---|
| yellow | 255 | 255 | 0 | grid cell centers |
| red | 255 | 0 | 0 | burst cone |
| blue | 0 | 0 | 255 | default component intersection |
| lt blue | 100 | 100 | 255 | default outside air intersection |
| lt green | 100 | 255 | 100 | default inside air intersection |
| purple | 255 | 0 | 255 | default critical component intersection |
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:
Table 3. Color Key for Frame Buffer Image
| Color | R | G | B | Representation |
|---|---|---|---|---|
| red | 255 | 0 | 0 | axis of grid |
| black | 0 | 0 | 0 | grid cell boundaries |
| blue | 0 | 0 | 255 | outside of grid |
| lt grey | 200 | 200 | 200 | shot missed target |
| white | 255 | 255 | 255 | shot hit target |
| lt green | 200 | 255 | 200 | burst occurred but hit no critical components |
| pink | 255 | 200 | 200 | burst occurred and hit some critical components |
| purple | 255 | 0 | 255 | a ground burst occurred |
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.