User Commands

Start a /bin/sh shell process for the user. The mged> prompt will be replaced by a system prompt for the shell, and the user may perform any legal shell commands. The mged process waits for the shell process to finish, which occurs when the user exits the shell. This only works in a command window associated with a tty (i.e., the window used to start mged in classic mode).

3ptarb [arb_name x1 y1 z1 x2 y2 z2 x3 y3 z3 x|y|z coord1 coord2 thickness]

Build an ARB8 shape by extruding a quadrilateral through a given thickness. The arguments may be provided on the command line; if they are not, they will be prompted for. The x1, y1, and z1 are the coordinates of one corner of the quadrilateral. x2, y2, z2, and x3, y3, z3 are the coordinates of two other corners. Only two coordinates of the fourth point are specified, and the code calculates the third coordinate to ensure all four points are coplanar. The x|y|z parameter indicates which coordinate of the fourth point will be calculated by the code. The coord1 and coord2 parameters supply the other two coordinates. The direction of extrusion for the quadrilateral is determined from the order of the four resulting points by the right-hand rule; the quadrilateral is extruded toward a viewer for whom the points appear in counter-clockwise order.

Provide a list of available mged commands. The ?devel, ?lib, help, helpdevel, and helplib commands provide additional information on available commands.

Provide a list of available mged developer commands. The ?, ?lib, help, helpdevel, and helplib commands provide additional information on available commands.

Provide a list of available BRL-CAD library interface commands. The ?, ?devel, help, helpdevel, and helplib commands provide additional information on available commands.

B [-R -A -o -s -C#/#/# ] <objects | attribute name/value pairs>

Clear the mged display of any currently displayed objects, then display the list of objects provided in the parameter list. Equivalent to the Z command followed by the command draw <objects>. The -C option provides the user a way to specify a color that overrides all other color specifications including combination colors and region id-based colors. The -A and -o options allow the user to select objects by attribute. The -s option specifies that subtracted and intersected objects should be drawn with solid lines rather than dot-dash lines. The -R option means do not automatically resize the view if no other objects are displayed. See the draw command for a detailed description of the options.

E [-s] <objects>

Display objects in an evaluated form. All the Boolean operations indicated in each object in objects will be performed, and a resulting faceted approximation of the actual objects will be displayed. Note that this is usually much slower than using the usual draw command. The -s option provides a more accurate, but slower, approximation.

M 1|0 xpos ypos

Send an mged mouse (i.e., defaults to a middle mouse button) event. The first argument indicates whether the event should be a button press (1) or release (0). The xpos and ypos arguments specify the mouse position in mged screen coordinates between -2047 and +2047. With the default bindings, an mged mouse event while in the viewing mode moves the view so that the point currently at screen position (xpos, ypos) is repositioned to the center of the mged display (compare to the center command). The M command may also be used in other editing modes to simulate an mged mouse event.

Zap (i.e., clear) the mged display.

adc [-i] [subcommand]

This command controls the angle/distance cursor. The adc command with no arguments toggles the display of the angle/distance cursor (ADC). The -i option, if specified, causes the given value(s) to be treated as increments. Note that the -i option is ignored when getting values or when used with subcommands where this option makes no sense. You can also control the position, angles, and radius of the ADC using a knob or the knob command.

This command accepts the following subcommands:

ae [-i] azimuth elevation [twist]

Set the view orientation for the mged display by rotating the eye position about the center of the viewing cube. The eye position is determined by the supplied azimuth and elevation angles (degrees). The azimuth angle is measured in the xy plane with the positive x direction corresponding to an azimuth of 0˚. Positive azimuth angles are measured counter-clockwise about the positive z axis. Elevation angles are measured from the xy plane with +90˚ corresponding to the positive z direction and -90 corresponding to the negative z direction. If an optional twist angle is included, the view will be rotated about the viewing direction by the specified twist angle. The -i option results in the angles supplied being interpreted as increments.

analyze [arb_name]

The analyze command displays the rotation and fallback angles, surface area, and plane equation for each face of the ARB specified on the command line. The total surface area and volume and the length of each edge are also displayed. If executed while editing an ARB, the arb_name may be omitted, and the ARB being edited will be analyzed.

The animmate command starts the Tcl/Tk-based animation tool. The capabilities and correct use of this command are too extensive to be described here, but there is a tutorial available.

apropos keyword

The apropos command searches through the one-line usage messages for each mged command and displays the name of each command where a match is found.

aproposdevel keyword

The aproposdevel command searches through the one-line usage messages for each mged developer command and displays the name of each command where a match is found.

aproposlib keyword

The aproposlib command searches through the one-line usage messages for each BRL-CAD library interface command and displays the name of each command where a match is found.

arb arb_name rotation fallback

The arb command creates a new ARB shape with the specified arb_name. The new ARB will be 20 inches by 20 inches and 2 inches thick. The square faces will be perpendicular to the direction defined by the rotation and fallback angles. This direction can be determined by interpreting the rotation angle as an azimuth and the fallback angle as an elevation as in the ae command.

arced comb/memb anim_command

The objects in a BRL-CAD model are stored as Boolean combinations of primitive shapes and/or other combinations. These combinations are stored as Boolean trees, with each leaf of the tree including a corresponding transformation matrix. The arced command provides a means for directly editing these matrices. The first argument to the arced command must identify the combination and which member’s matrix is to be edited. The comb/memb argument indicates that member memb of combination comb has the matrix to be edited. The remainder of the arced command line consists of an animation command to be applied to that matrix. The available animation commands are:

By default, the matrix commands expect a list of 16 matrix elements to define a matrix. The xlate option may be used along with three translation distances in the x, y, and z directions (in mm) as a shorthand notation for a matrix that is pure translation. Similarly, the rot option along with rotation angles (degrees) about the x, y, and z axes may be used as shorthand for a matrix that is pure rotation.

area [tolerance]

The area command calculates an approximate presented area of one region in the mged display. For this command to work properly, a single BRL-CAD region must be displayed using the E command. The tolerance is the distance required between two vertices in order for them to be recognized as distinct vertices. This calculation considers only the minimum bounding polygon of the region and ignores holes.

arot x y z angle

The arot command performs a rotation about the specified axis (x y z) using screen units (-2048 to +2048). The amount of rotation is determined by angle, which is in degrees. Exactly what is rotated and how it is rotated are dependent on MGED s state as well as the state of the display manager. For example, in normal viewing mode, this command simply rotates the view. However, in primitive edit mode, it rotates the shape being edited.

attach [-d display_string] [-i init_script] [-n name] [-t is_toplevel] [-W width] [-N height] [-S square_size] win_type

The attach command is used to open a display window. The set of supported window types includes X and ogl. It should be noted that attach no longer releases previously attached display windows (i.e., multiple attaches are supported). To destroy a display window, use the release command.

attr get|set|rm|append|show object_name [arguments]

The attr command is used to create, change, retrieve, or view attributes of database objects. The arguments for set and append subcommands are attribute name/value pairs. The arguments for get, rm, and show subcommands are attribute names. The set subcommand sets the specified attributes for the object. The append subcommand appends the provided value to an existing attribute, or creates a new attribute if it does not already exist. The get subcommand retrieves and displays the specified attributes. The rm subcommand deletes the specified attributes. The show subcommand does a get and displays the results in a user readable format. Note that the attribute names may not contain embedded white space, and if attribute values contain embedded white space, they must be surrounded by {} or double quotes.

The autoview command resets the view_size and the view center such that all displayed objects are within the view.

bev [-t] [-P#] new_obj Boolean_formula

The bev command performs the operations indicated in the Boolean_formula and stores the result in new_obj. The new_obj will be stored as an NMG shape (it may be converted to a polysolid by using the nmg_simplify command). If the -t option is specified, then the resulting object will consist entirely of triangular facets. The default is to allow facets of any complexity, including holes. The -P option specifies the number of CPUs to use for the calculation (however, this is currently ignored). Only simple Boolean_formulas are allowed. No parentheses are allowed and the operations are performed from left to right with no precedence. More complex expressions must be expressed as BRL-CAD objects using the r, g, or c commands and evaluated using the facetize or ev commands.

bo [-o|-i pattern type] dest source

The bo command is used to create or retrieve binary opaque objects. One of -i or -o must be specified.

The -o option outputs or extracts a binary object from the database object source to a file called dest.

The -i option inputs or imports a file called source into a binary object called dest in the database. There are two additional arguments that must be specified with the -i option: pattern and type. Currently, only uniform binary objects (arrays of values) are supported. As a result, the pattern is always u for uniform pattern. The type can be one of the following:

bot_condense new_bot_primitive old_bot_primitive

The bot_condense command is used to eliminate unused vertices from a BOT primitive. It returns the number of vertices eliminated.

bot_decimate c maximum_chord_error n maximum_normal_error e minimum_edge_length new_bot_primitive old_bot_primitive

The bot_decimate command reduces the number of triangles in the old_bot_primitive and saves the results to the new_bot_primitive. The reduction is accomplished through an edge decimation algorithm. Only changes that do not violate the specified constraints are performed. The maximum_chord_error parameter specifies the maximum distance allowed between the original surface and the surface of the new BOT primitive in the current editing units. The maximum_normal_error specifies the maximum change in surface normal (degrees) between the old and new surfaces. The minimum_edge_length specifies the length of the longest edge that will be decimated. At least one constraint must be supplied. If more than one constraint is specified, then only operations that satisfy all the constraints are performed.

bot_face_fuse new_bot_primitive old_bot_primitive

The bot_face_fuse command is used to eliminate duplicate faces from a BOT solid. It returns the number of faces eliminated.

bot_face_sort triangles_per_piece bot_primitive1 [bot_primitive2 bot_primitive3 …​]

The bot_face_sort command is used to sort the list of triangles that constitutes the BOT primitive to optimize it for raytracing with the specified number of triangles per piece. Most BRL-CAD primitives are treated as a single object when a model is being prepared for raytracing, but BOT primitives are normally broken into pieces to improve performance. The raytracer normally uses four triangles per piece.

bot_vertex_fuse new_bot_solid old_bot_primitive

The bot_vertex_fuse command is used to eliminate duplicate vertices from a BOT solid. It returns the number of vertices eliminated. No tolerance is used, so the vertices must match exactly to be considered duplicates.

build_region [-a region_num] tag start_num end_num

The build_region command builds a region from existing solids that have specifically formatted names based on the provided tags and numbers. The created region will be named tag.rx, where x is the first number (starting from 1) that produces an unused region name. If the -a option is used, then the specified region_num will be used for x. If that region already exists, this operation will append to it. If that region does not exist, a new one will be created. The solids that will be involved in this operation are those with names of the form tag.s# or tag.s#o@, where # is a number between start_num and end_num inclusive, o is either u, -, or +, and @ is any number. The operators and numbers coded into the solid names are used to build the region.

c [-c|r] combination_name [Boolean_expression]

The c command creates a BRL-CAD combination with the name combination_name. The -r option indicates that the combination is a BRL-CAD region. The -c option is the default and indicates that the combination is not a region. The Boolean_expression allows parentheses. Where no order is specified, intersections are performed before subtractions or unions; then subtractions and unions are performed, left to right. Where there is no Boolean_expression and combination_name, a new empty combination will be created. If no Boolean_expression is provided, and combination_name does already exist and one of -c or -r is specified, then combination_name is flagged to agree with the indicated option. If a new region is created or an existing combination is flagged as a region with this command, its region-specific attributes will be set according to the current defaults (see regdef). The comb and r commands may also be used to create combinations.

cat <objects>

The cat command displays a brief description of each item in the list of objects. If the item is a primitive shape, the type of shape and its vertex are displayed. If the item is a combination, the Boolean formula for that combination including operands, operators, and parentheses is displayed. If the combination is flagged as a region, then that fact is also displayed along with the region’s ident code, air code, los, and GIFT material code.

center [x y z]

The center command positions the center of the mged viewing cube at the specified model coordinates. This is accomplished by moving the eye position while not changing the viewing direction. (The lookat command performs a related function by changing the viewing direction, but not moving the eye location.) The coordinates are expected in the current editing units. In case the coordinates are the result of evaluating a formula, they are echoed back. If no coordinates are provided, the current center coordinates (in current editing units, not mm) are printed and can be used in subsequent calculations.

It is often convenient to use the center of the view when visually selecting key locations in the model for construction or animation because of

This command provides the means to set and retrieve those values numerically.

check {subcommand} [options][objects…​]

The check command computes and reports a variety of characteristics of the objects specified from the opened database. The characteristics which can be computed include mass, centroid, moments of inertia, volume, overlaps, surface area, exposed air, gaps/voids, adjacent air and unconfined air. Only the objects from the database specified on the command line are analyzed.

The following are the sub-commands offered:

The following are the options offered:

color low high r g b str

The color command creates an entry in the database that functions as part of a color lookup table for displayed regions. The ident number for the region is used to find the appropriate color from the lookup table. The low and high values are the limits of region ident numbers to have the indicated rgb color (0-255) applied. The str parameter is intended to be an identifying character string, but is currently ignored. The current list of color table entries may be displayed with the prcolor command, and the entire color table may be edited using the edcolor command. If a color lookup table exists, its entries will override any color assigned using the mater command.

comb combination_name <operation object>

The comb command creates a new combination or extends an existing one. If combination_name does not already exist, then it will be created using the indicated list of operations and objects. If it does exist, the list of operations and objects will be appended to the end of the existing combination. The <operation object> list is expected to be in the same form as used in the r command. The c command may also be used to create a combination.

comb_color combination_name r g b

The comb_color command assigns the color rgb (0-255) to the existing combination named combination_name.

copyeval new_primitive path_to_old_ primitive

Objects in a BRL-CAD model are stored as Boolean trees (combinations), with the members being primitive shapes or other Boolean trees. Each member has a transformation matrix associated with it. This arrangement allows a primitive to be a member of a combination, and that combination may be a member of another combination, and so on. When a combination is displayed, the transformation matrices are applied to its members and passed down through the combinations to the leaf (primitive shape) level. The accumulated transformation matrix is then applied to the primitive before it is drawn on the screen. The copyeval command creates a new primitive object called new_primitive by applying the transformation matrices accumulated along the path_to_old_primitive to the leaf primitive shape object at the end of the path and saving the result under the name new_primitive. The path_to_old_primitive must be a legitimate path ending with a primitive shape.

copymat comb1/memb1 comb2/memb2

The copymat command copies the transformation matrix from a member of one combination to the member of another.

cp from_object to_object

The cp command makes a duplicate of an object (shape or combination). If from_object is a shape, then it is simply copied to a new shape named to_object. If from_object is a combination, then a new combination is created that contains exactly the same members, transformation matrices, etc., and it is named to_object.

cpi old_tgc new_tgc

The cpi command copies old_tgc (an existing TGC shape) to a new TGC shape (new_tgc), positions the new TGC such that its base vertex is coincident with the center of the top of old_tgc, and puts mged into the primitive edit state with new_tgc selected for editing. This command was typically used in creating models of wiring or piping runs; however, a pipe primitive has since been added to BRL-CAD to handle such requirements.

d <objects>

The d command deletes the specified list of objects from the mged display. This is a synonym for the erase command. Only objects that have been explicitly displayed may be deleted with the d command (use the who command to see a list of explicitly displayed objects). Objects that are displayed as members of explicitly displayed combinations cannot be deleted from the display with this command (see erase -r). Note that this has no effect on the BRL-CAD database itself. To actually remove objects from the database, use the kill command.

db command [args…​]

The db command provides an interface to a number of database manipulation routines. Note that this command always operates in units of millimeters. The command must be one of the following with appropriate arguments:

db_glob cmd_string

Globs cmd_string against the MGED database resulting in an expanded command string.

dbconcat [-s/-p] [-t] [-u] [-c] database_file [affix]

The dbconcat command concatenates an existing BRL-CAD database to the database currently being edited. If an affix is supplied, then all objects from the database_file will have that affix added to their names.

The -s option indicates that the affix is a suffix, while the -p option (default) indicates that the affix is a prefix. Note that each BRL-CAD object must have a unique name, so care must be taken not to dbconcat a database that has objects with names the same as objects in the current database. The dup command may be used to check for duplicate names. If the dup command finds duplicate names, use the prefix option to both the dup and dbconcat commands to find a prefix that produces no duplicates. If duplicate names are encountered during the dbconcat process, and no affix is supplied, computer-generated prefixes will be added to the object names coming from the database_file (but member names appearing in combinations will not be modified, so this is a dangerous practice and should be avoided).

If the -t option is specified, then the title of the database_file will become the new title of the current BRL-CAD database. If the -u option is specified, the units of the current database will be set to that of the database_file being concatted. The -c option specifies that the region color table in the concatted database_file should replace any region color table in the current BRL-CAD database.

debugbu [hex_code]

The debugbu command allows the user to set or check the debug flags used by libbu. With no arguments, the debugbu command displays all the possible settings for the bu_debug flag and the current value. When a hex_code is supplied, that value is used as the new value for bu_debug. Similar debug commands for other BRL-CAD libraries are debuglib for librt and debugnmg for the NMG portion of librt.

The debugdir command displays a dump of the in-memory directory for the current database file. The information listed for each directory entry includes:

debuglib [hex_code]

The debuglib command allows the user to set or check the debug flags used by librt. With no arguments, the debuglib command displays all the possible settings for the librt debug flag and the current value. When a hex_code is supplied, that value is used as the new value for the flag. Similar debug commands for other BRL-CAD libraries are debugbu for libbu and debugnmg for the NMG portion of librt.

debugnmg [hex_code]

The debugnmg command with no options displays a list of all possible debug flags available for NMG processing. If the command is invoked with a hex number argument, that value is used as the new value for the NMG debug flag. Similar debug commands for other BRL-CAD libraries are debuglib for librt and debugbu for libbu.

decompose NMG_shape [prefix]

The decompose command processes an NMG shape and produces a series of new NMG shapes consisting of each maximally connected shell in the original NMG shape. If an optional prefix is supplied, the resulting NMG shapes will be named by using the prefix and adding an underscore character and a number to make the name unique. If no prefix is supplied, the default prefix sh will be used.

delay seconds microseconds

The delay command provides a delay of the specified time before the next command will be processed.

dm subcommand [args]

The dm command provides a means to interact with the display manager at a lower level. The dm command accepts the following subcommands:

draw [-R -A -s -o -C#/#/#] <objects | attribute name/value pairs>

Add <objects> to the display list so that they will appear on the MGED display. The e command is a synonym for draw.

dup file [prefix]

The dup command checks the specified file (which is expected to contain a BRL-CAD model) for names that are the same as those in the current model. If a prefix is included on the command line, all names in the specified file will have that prefix added to their names before comparison with the current model. This command is often used prior to invoking the dbconcat command to ensure that there are no name clashes.

e [-R -A -o -s -C#/#/#] <objects| attribute name/value pairs>

The e command adds the objects in the argument list to the display list so that they will appear on the MGED display. This is a synonym for the draw command; see that entry for a full list of options. The -C option provides the user a way to specify a color that overrides all other color specifications including combination colors and region-id-based colors. The -A and -o options allow the user to select objects by attribute. The -s specifies that subtracted and intersected objects should be drawn with solid lines rather than dot-dash lines. The -R option means do not automatically resize the view if no other objects are displayed.

eac <aircodes>

The eac command adds all the regions in the current model that have one of the aircodes in the argument list to the display list so that they will appear on the MGED display. Regions that have nonzero ident numbers will not be listed by this command. The whichair command will perform the same search, but just lists the results.

echo text

The echo command merely echos whatever text is provided as an argument on the command line. This is intended for use in MGED scripts.

edcodes <objects>

The edcodes command puts the user into an editor to edit a file that has been filled with the ident, air code, material code, LOS, and name of all the regions in the specified objects. The user may then modify the entries (except for the names). The editor used is whatever the user has set in the environment variable EDITOR. If EDITOR is not set, then /bin/ed is used.

The edcolor command puts the user into an editor to edit a file that has been filled with the ident based color lookup table. The entire table may be seen with the prcolor command, and entries may be added using the color command. The editor used is whatever the user has set in the environment variable EDITOR. If EDITOR is not set, then /bin/ed is used.

edcomb combname R|G regionid air_code los [material_code]

The edcomb command allows the user to modify the attributes of a combination. The combname is the name of the combination to be modified. An R flag indicates that the region flag should be set; otherwise, the region flag is unset. If the region flag is not being set, then the remainder of the attributes are ignored. If the region flag is being set, then the region_id, aircode, los, and material_code are set according to the arguments supplied.

edgedir [x y z]|[rot fb]

The edgedir command allows the user to set the direction of an edge by specifying a direction vector in the form of x, y, and z components or via rotation and fallback angles. This can only be done while moving an edge of an ARB.

edmater <combinations>

The edmater command places the user in an editor ready to edit a file filled with shader arguments for the combinations listed on the command line. The arguments placed in the file for editing are the shader name and its own arguments, RGB color, RGB_valid flag, and the inheritance flag. The editor used is whatever the user has set in the environment variable EDITOR. If EDITOR is not set, then /bin/ed is used.

eqn A B C

The eqn command allows the user to rotate the face of an ARB shape by providing the coefficients of an equation of the desired plane for the face. The coefficients A, B, and C are from the plane equation:

The user must be editing an ARB shape and be rotating a face of the ARB for this command to have any effect. When entering such a state, the user will be asked which of the face vertices should be held constant, and from this information the D coefficient of the equation is determined.

erase <objects>

The erase command deletes the specified list of objects from the MGED display. This is a synonym for the d command. Only objects that have been explicitly displayed may be deleted with the erase command (use the who command to see a list of explicitly displayed objects). Objects that are displayed as members of explicitly displayed combinations cannot be deleted from the display with this command (see erase -r). Note that this has no effect on the BRL-CAD database itself. To actually remove objects from the database, use the kill command.

ev [-dfnrstuvwST] [-P#] [-C#/#/#] <objects>

The ev command evaluates the objects specified by tessellating all primitive shapes in the objects and then performing any Boolean operations specified in the objects. The result is then displayed in the MGED display according to the specified options:

The exit command ends the MGED process. This is a synonym for the quit command.

expand regular_expression

The expand command performs matching of the regular_expression with the names of all the objects in the database. It returns all those that successfully match.

expand_comb prefix comb …​

The expand_comb will create a new combination object prefix. For each Boolean node in the original tree of the combination a new combination will be created. Each combination constructed will contain a single Boolean operation of two leaf nodes. The leaf nodes will be named prefixl and prefixr for the left and right nodes of the tree respectively. Sub-nodes will have l and r suffixes added based upon whether they are left or right children of the node.

Note that regions, combinations and objects created with the g command (sometimes colloquially referred to as groups) are all combinations, and can be expanded with this command.

extrude #### distance

The extrude command modifies an ARB shape by extruding the specified face through the specified distance to determine the position of the opposing face. The face to be extruded is identified by listing its vertex numbers as they are labeled in the MGED display when the ARB is edited. Note that the face identified is not moved, but the opposite face is adjusted so that it is the specified distance from the specified face. The order that the vertex numbers are listed determines the direction of the extrusion using the right-hand rule.

eye_pt x y z

The eye_pt command positions the eye point to the given x, y, and z coordinates (specified in mm).

facedef #### [a|b|c|d parameters]

The facedef command allows the user to redefine any face of an ARB8 shape. The user must be in Primitive Edit Mode with an ARB selected for editing. The optional parameters may be omitted, and MGED will prompt for the missing values. The options are:

facetize [-ntT] -P#] new_object old_object

The facetize command creates new_object as a BOT shape by tessellating all the primitive shapes in old_object and then performing any Boolean operations specified in old_object. The -T option indicates that all faces in the new_object should be triangulated. The -n option specifies that the resulting shape should be saved as an NMG shape. The -t option is to create TNURB faces rather than planar approximations (this option is still under development). The -P option is intended to allow the user to specify the number of CPUs to use for this command, but it is currently ignored.

find <objects>

The find command displays all combinations that have any of the objects specified as a member.

fracture NMG_shape [prefix]

The fracture command creates a new NMG shape for every face in the specified NMG_shape. The new shapes will be named by adding an underscore and a number to the prefix. If no prefix is specified, then the NMG_shape name provided is used in place of the prefix.

g groupname <objects>

The g command creates a special type of combination often referred to as a group. This builds a combination by unioning together all the listed objects. If groupname already exists, then the list of objects will be unioned to the end of it. (Note that an existing groupname is not restricted to being a group; any combination is legal.) Other commands to build combinations are c, r, or comb.

The garbage_collect command eliminates unused space in a BRL-CAD database file.

gui [-config b|c|g] [-d display_string] [-gd graphics_display_string] [-dt graphics_type] [-id name] [-c -h -j -s]

This command is used to create an instance of MGED s default Tcl/Tk graphical user interface (GUI). The following options are allowed:

help [command]

The help command returns a list of available MGED commands along with a one-line usage message for each. If a command is supplied as an argument, the one-line usage message for that command is returned. The helpdevel, helplib, ?, ?devel, and ?lib commands provide additional information on available commands.

helpdevel [command]

The helpdevel command returns a list of available developer commands along with a one-line usage message for each. If a command is supplied as an argument, the one-line usage message for that command is returned. The help, helplib, ?, ?devel,and ?lib commands provide additional information on available commands.

helplib [command]

The helplib command returns a list of available library commands along with a one-line usage message for each. If a command is supplied as an argument, the one-line usage message for that command is returned. The help, helpdevel, ?, ?devel, and ?lib commands provide additional information on available commands.

hide <objects>

The hide command sets the hidden flag for the specified objects. When this flag is set, the objects do not appear in t or ls command outputs. The -a option on the ls or t command will force hidden objects to appear in its output.

history [-delays]

The history command displays the list of commands executed during the current MGED session. The one exception is the hist_add command, which can add a command to the history list without executing it. If the -delays option is used, then the delays between commands will also be displayed.

i obj_name comb_name [operation]

The i command adds obj_name to the end of the combination named comb_name. The operation may be +, -, or u. If no operation is specified, u is assumed. If comb_name does not exist, it is created.

idents file_name <objects>

The idents command places a summary of the regions in the list of objects specified in the file specified. If any regions include other regions, then only the first encountered region in that tree will be listed. The resulting file will contain two lists of regions, one in the order encountered in the list of objects, and the other ordered by ident number. The data written for each region includes (in this order) a sequential region count, the ident number, the air code, the material code, the LOS, and the path to the region.

ill obj_name

The ill command performs the function of selecting an object after entering solid (i.e., primitive) illuminate or object illuminate mode. In solid illuminate mode, this command selects the specific shape for editing. In object illuminate mode, this command selects the leaf object for the object path, then the user may use the mouse to select where along the object path the editing should be applied. In both modes, the ill command will only succeed if the specified obj_name is only referenced once in the displayed objects; otherwise a multiply referenced message will be displayed. If the ill command fails, the user must resort to either using the mouse to make the selection, or using aip and M 1 0 0.

in [-f] [-s] new_shape_name shape_type <parameters>

The in command allows the user to type in the arguments needed to create a shape with the name new_shape_name of the type shape_type. The command may be invoked with no arguments, and it will prompt the user for all needed information. The -s option will invoke the primitive edit mode on the new shape immediately after creation. The -f option does not draw the new shape, and therefore the -s option may not be used in conjunction with -f. The possible values for shape_type are:

inside [outside_shape_name new_inside_shape_name <parameters>]

The inside command creates a new shape that is inside an existing shape. This command is typically used to create an inside shape that can be subtracted from the original shape to produce a hollow shell. The command is typically used with no arguments, and it prompts the user for all needed information; however, all the parameters may be supplied on the command line. If MGED is in primitive edit mode when the inside command is issued, then the shape currently being edited will be used as the outside_shape. Similarly, if MGED is in matrix edit mode when the inside command is executed, then the current key shape will be used as the outside shape.

item region_name ident_number [air_code [material_code [LOS]]]

The item command sets the values of ident_number, aircode, material_code, and LOS for the specified region.

joint command [options]

articulation/animation commands (experimental)

journal [-d] [journal_file_name]

The journal command starts or stops the journaling of MGED commands to a file. If executed with no arguments, the command stops journaling. If journal_file_name is provided, that file will become the recipient of the journaling. If a -d option is also provided, the journaling will include the delays between commands. Journaling is off by default.

keep keep_file <objects>

The keep command copies the objects specified to the keep_file. If keep_file does not exist, it is created. If keep_file does exist, the objects are appended to it. The keep_file is a BRL-CAD database file. The objects in the list must exist in the current database.

keypoint [x y z | reset]

The keypoint command without any options displays the current keypoint setting. If a point is specified, then that point becomes the keypoint. If reset is specified, then the default keypoint is restored. The keypoint is used as the center of rotation and scaling in primitive edit or matrix edit (formerly known as object edit) modes. This command has no effect when used in nonediting modes.

kill [-f] <objects>

The kill command deletes the specified objects from the current database. This command affects only the objects actually listed on the command line. If a combination is killed, its members are not affected. If the -f option is specified, then kill will not complain if some, or all, of the objects specified do not actually exist in the database. Note that the objects are killed immediately. There is no need for a write file command in MGED, and there is no undo command. Use this command with caution. Other commands that remove objects from the database are killall and killtree.

killall <objects>

The killall command deletes the specified objects from the current database and removes all references to them from all combinations in the database. Note that the objects are killed immediately. There is no need for a write file command in MGED, and there is no undo command. Use this command with caution. Other commands that remove objects from the database are kill and killtree.

killtree <objects>

The killtree command deletes the specified objects from the current database and recursively deletes all objects referenced by any of those objects. If one of the objects listed is a combination, then that combination as well as any objects that are members of that combination will be deleted. If a member of that combination is itself a combination, then all of its members will also be destroyed. This continues recursively until the primitive shapes are reached and destroyed. Note that the objects are killed immediately. There is no need for a write file command in MGED, and there is no undo command. Use this command with extreme caution. Other commands that remove objects from the database are kill and killall.

knob [-e -i -m -v] [-o v|m|e|k] [zap|zero|(id [value])]

The knob command is used internally by MGED in the processing of knob input devices and is not recommended for users. The knob command provides a method for simulating knob input. With no options, it will display the current values for the knobs. With the zap or zero command provided, all the knob values will be reset to zero. If an id and value are provided, the specified knob setting will be simulated. If the -i option is specified, then the value provided will be used as an increment to be applied to the indicated knob. The knobs have different functions depending on the current mode. For example, if in primitive or matrix edit mode and a rotation or translation function is selected, the knob effects are applied to the edited object by default. However, the -v (view coordinates) and -m (model coordinates) options may be used to adjust the view without modifying primitives or matrices. The -e option allows the knob effects to be applied to the edited object when they would normally be applied to the view. The -o option allows the origin of rotation to be specified with v, m, e, and k, indicating view, model, and eye and keypoint, respectively. The units for value are degrees for rotation and local units for translation. The available knob ids are:

l [-r] <objects>

The l command displays a verbose description about the specified list of objects. If a specified object is a path, then any transformation matrices along that path are applied. If the final path component is a combination, the command will list the Boolean formula for the combination and will indicate any accumulated transformations (including any in that combination). If a shader and/or color has been assigned to the combination, the details will be listed. For a region, its ident, air code, material code, and LOS will also be listed. For primitive shapes, detailed shape parameters will be displayed with the accumulated transformation applied. If the -r (recursive) option is used, then each object on the command line will be treated as a path. If the path does not end at a primitive shape, then all possible paths from that point down to individual shapes will be considered. The shape at the end of each possible path will be listed with its parameters adjusted by the accumulated transformation.

labelvert <objects>

The labelvert command labels the vertices of the indicated objects with their coordinate values in the MGED display window. The objects must have already been displayed using e, E, ev, B, or any other command that results in the display of an object.

listeval [path]

Combinations may include transformation matrices to be applied to their members. A path through a series of combinations and ending with a primitive shape represents that primitive shape with the transformations accumulated through the path applied to it. The listeval command displays primitive shape parameters after applying the accumulated transformations from the indicated path. If the specified path does not end at a primitive shape, then all possible paths from the indicated path to any primitive shape will be evaluated and displayed.

The loadtk command loads the initialization for the Tk window library. This is normally done automatically when the user attaches any display manager for MGED. If no display manager is attached, then the user must execute loadtk prior to using any Tk facilities.

lookat x y z

The lookat command adjusts the current view in MGED such that the eye is looking in the direction of the given coordinates, but does not move the eye point nor change the view_size. This is similar to just rotating the viewers head to look at the specified point, putting that point in the center of the MGED display. The center command performs a similar function, but moves the eye_pt without changing the viewing direction.

ls [-A -o -a -c -r -s -p -l] [objects]

The ls command with no object argument lists the name of every object in the database (in alphabetical order) except for those marked as hidden with the hide command. If the object argument is supplied, only those objects are listed. The object argument may include regular expressions. If the -A option is used, then the arguments are expected to be a list of attribute name/value pairs, and objects having attributes that match the provided list are listed. By default, an object must match all the specified attributes in order to be listed; however, the -o flag indicates that an object matching at least one attribute name/value pair should be listed. See the attr command for information on how to set or get attributes. Regular expressions are not supported for attributes. The following options are also allowed:

The ls command is a synonym for the t command. Note that when any of the above options are used, the output is not formatted.

make -t | new_shape type

The make command creates a new_shape of the indicated type. The new_shape is sized according to the current view_size and is dependent on the type. The possible values for type are:

mater combination [shader_parameters [RGB [inheritance]]]

The mater command assigns shader parameters, RGB color, and inheritance to an existing combination. The information may be included on the command line; otherwise the user will be prompted for it. Some available shaders are:

matpick # | combination/member

The matpick command selects which matrix in the illuminated path should be edited. A number may be specified with 0 being the topmost selection. A combination/member may be specified to indicate that the matrix in combination that corresponds to member is to be edited. This command is only useful in matrix edit mode at the point where the user is selecting which matrix in the illuminated path should be edited. It is used internally by MGED; the user should generally use the mouse to make this selection.

mirface #### x|y|z

The mirface command modifies an ARB shape by mirroring the indicated face along the selected x, y, or z axis. An ARB shape must be selected for editing. Not all faces of all ARB types may be edited using this command.

mirror old_object new_object x|y|z

The mirror command creates new_object by duplicating old_object and reflecting it along the indicated axis. If old_object is a primitive shape, then a new shape is created, with parameters adjusted to accomplish the mirror operation. If old_object is a combination, then new_object will simply be a copy of old_object with all of its members matrices set to perform the appropriate reflection.

mrot x y z

Rotate the view using model x y z.

mv old_name new_name

The mv command changes the name of old_name to new_name. Note that this does not change any references to old_name that may appear in other combinations in the database. The mvall command will change an object s name everywhere.

mvall old_name new_name

The mvall command changes the name of old_name to new_name. This will also change any references to old_name that may appear in other combinations in the database. The mv command will change an object s name without changing references to it. The prefix command will also change the names and references of objects.

nirt [nirt_args]

The nirt command runs the nirt program that is distributed with BRL-CAD to intersect a single ray with the displayed objects. By default, nirt is run using the current database and the currently displayed objects, and it uses the current eye point as the ray start point and the current viewing direction as the ray direction. This effectively fires a ray at the center of the MGED display. The resulting collection of intersections between the ray and the objects is listed. Additional arguments may be supplied on the nirt command line. See the man page of nirt for more details.

nmg_collapse old_nmg_shape new_nmg_shape maximum_error_dist [minimum_angle]

The nmg_collapse command simplifies an existing nmg_shape by a process of edge decimation. Each edge in the old_nmg_shape is considered; if it can be deleted without creating an error greater than the specified maximum_error_dist, then that edge is deleted. If a minimum_angle is specified (degrees), then the edge will not be deleted if it would create a triangle with an angle less than minimum_angle. The resulting shape is saved in new_nmg_shape. The old_nmg_shape must have been triangulated previous to using the nmg_collapse command. The resulting shape consists of all triangular faces.

nmg_simplify [arb|tgc|poly] new_shape nmg_shape

The nmg_simplify command attempts to convert an existing nmg_shape to a simpler primitive shape type. The user may specify which type to attempt by including arb, tgc, or poly on the command line. If no shape type is specified, all will be attempted in the above order. If tgc is specified, the code will attempt to determine if the nmg_shape is an approximation of a TGC shape.

oed path_lhs path_rhs

The oed command places MGED directly into the matrix edit mode. The path_rhs must be a path to a primitive shape, and path_lhs must be a path to a combination that includes the first component of path_rhs as one of its members. Also, path_rhs/path_lhs must be a path that is currently displayed in mged. The edited matrix will be the matrix in the final component of path_lhs that corresponds to the first component of path_rhs. The last component in path_rhs is used as the reference shape during object editing.

opendb [database.g]

The opendb command closes the current database file and opens database.g. If database.g is not found, the current database is left open. If database.g is not specified on the command line, the name of the current database file is returned.

orientation x y z w

The orientation command sets the view direction for MGED from the quaternion specified on the command line.

orot [-i] xdeg ydeg zdeg

The orot command performs a rotation of an object during matrix edit. The rotation is performed, in order: xdeg about the x axis, then ydeg about the y axis, and finally zdeg about the z axis. If the -i flag is given, then the angles are interpreted as increments to the last object rotation. The rotobj command is a synonym for orot.

oscale scale_factor

The oscale command of matrix edit mode modifies the matrix to perform a uniform scale operation. A scale_factor of 2 doubles the size of the associated object, and a scale_factor of 0.5 reduces it by half.

overlay plot_file [name]

The overlay command plots the specified UNIX plot_file in the MGED display. Phony object names are created for each part of the plot file that is in a unique color. The names are created by adding a color to the specified name, or to _PLOT_OVER if no name is provided. The color suffix is built by converting the RGB color to a six digit hex number. Each color corresponds to 2 hex digits, so that white becomes ffffff, red becomes ff0000, green is 00ff00, etc.

p value1 [value2 value3]

The p command provides precise control over primitive editing operations that would normally be done using the mouse or knobs. For example, a shape rotate may be performed by selecting rotate from the primitive edit menu, then providing the rotation angles with the p command. A command of p 0 30 0 would rotate the edited shape through 30˚ about the y axis. Similarly, many of the individual parameters of the edited shape may be set exactly using the p command. If the scale H menu item is selected while editing a TGC, then the value1 supplied with a p command specifies the actual length of the height vector for that TGC. This method is the recommended technique to set precise values for shape parameters. The translate and rotobj commands provide a similar capability for object editing.

pathlist <combinations>

The pathlist command lists all existing paths that start from the specified combinations and end at a primitive shape.

paths path_start

The paths command lists all existing paths that start from the specified path_start and end at a primitive shape. The path_start may be specified by / separated components, or they may be separated by spaces (but not both).

permute tuple

The permute command permutes the vertex labels for the face of an ARB> shape that is currently being edited. The tuple indicates which face is affected and also indicates the desired result. The tuple is formed by concatting the list of vertex numbers for the face in the order desired such that the first vertex listed will become vertex number one (and therefore the default keypoint). Only a sufficient number of vertices to disambiguate need be included in the tuple. Note that this has no effect on the geometry of the ARB, but may affect any texture mapping involving this shape.

plot [-float] [-zclip] [-2d] [-grid] out_file | "|" filter

The plot command creates a UNIX plot of the current MGED display. If an output_file is specified, the plot is stored in that file. If a filter is specified, the output is sent to that filter. The -float option requests a plot file with real numbers rather than integers. The -zclip option requests that the plot be clipped to the viewing cube in the Z-direction. The -2d option requests a two-dimensional plot (the default is 3D). The -grid option is intended to include a grid in the plot, but is currently not implemented.

The prcolor command lists the entries in the ident-based color table. The ident number for a displayed region is used to find the appropriate color from the lookup table. The low and high values are the limits of region ident numbers to have the indicated r g b color (0-255) applied. The color table entries may be modified using the color command, and the entire color table may be edited using the edcolor command. If a color lookup table exists, its entries will override any color assigned using the mater command.

prefix new_prefix <objects>

The prefix command changes the name of all the objects listed by adding the specified new_prefix. All references to the objects will also be changed. The mvall command performs a similar function.

press button_label

The press command simulates the pressing of a button. All of these button actions can be run directly as a command. The button_label indicates which button to simulate. The available buttons are:

preview [-v] [-d delay] [-D start_frame_number] [-K end_frame_number] rt_script_file

The preview command allows the user to preview animation scripts in MGED. The -d option provides a delay in seconds to be applied between each frame (the default is no delay). The -D option allows the user to specify a starting frame number, and the -K option allows the specification of an ending frame number. The -v flag indicates that the objects displayed in the MGED graphics window should be displayed in evaluated mode, as would be the result of the ev command. Note that this may significantly slow the preview.

prj_add [-t] [-b] [-n] shaderfile [image_file] [image_width] [image_height]

The prj_add command appends information to the specified shaderfile. The information appended is in the form required by the projection shader (prj) and includes the image_file (typically a pix file), the image_width and image_height, and current view parameters from the MGED display. The resulting shaderfile may then be used as the parameter to the prj shader. Before executing this command, the region wireframe display in MGED should be aligned with the image_file (underlaid in MGED’s framebuffer) and the image_file should have the same height and width as the mged display. The -t option indicates that the image should be projected through the object. The -n option requests that antialiasing not be done.

ps [-f font] [-t title] [-c creator] [-s size_in_inches] [-l line_width] output_file

The ps command temporarily attaches the Postscript display manager and outputs the current MGED display to the specified output_file in PostScript format. The -f option allows the font to be user-specified. The -t option allows the user to provide a title (the default is No Title). The -c option allows the user to specify the creator of the file (the default is LIBDM dm-ps). The -s specifies the size of the drawing in inches. The -l specifies the width of the lines drawn.

pull <objects>

The pull command pulls the effects of all transformation matrices that appear in any primitive shapes or combinations in the trees up to the specified objects heading the tree. This will restore the original the parameters of the primitive shapes if any of the transformation matrices are not identity matrices. All the transformation matrices visited up the tree will be set to the current transformation matrix. This command will fail, and no changes will be made, if the head is referenced by a primitive shape.

push <objects>

The push command forces the effects of all transformation matrices that appear in any combinations in the trees from the specified objects down to the primitive shapes. This will change the parameters of the primitive shapes if any of the transformation matrices are not identity matrices. All the transformation matrices visited will be set to identity matrices. This command will fail, and no changes will be made, if any primitive shape referenced by the list of objects is positioned differently in two or more combinations. The xpush command will perform a similar function, even if some shapes are multiply referenced.

putmat comb_name/member_name {I | m0 m1 m2 m3 …​ m16}

The putmat command replaces the existing transformation matrix in the combination specified that corresponds to the member specified. The transformation matrix may be specified with an I to indicate the identity matrix, or it may be specified as 16 elements listed row-by-row. The copymat command allows the user to copy an existing transformation matrix.

The q command ends the MGED process. Note that there is no write database command in MGED. All changes are made to the database as the user performs them. Therefore, a q command will not restore the database to its pre-edited state. This is a synonym for the quit command.

qorot x y z dx dy dz angle

The qorot command rotates an object through the specified angle (in degrees). This command requires that MGED already be in matrix edit mode. The edited object is rotated about the axis defined by the start point (x y z) and the direction vector (dx dy dz).

qray [subcommand]

Get/set query_ray characteristics. Without a subcommand, the usage message is printed. The qray command accepts the following subcommands:

query_ray [nirt_args]

The query_ray command runs the nirt program that is distributed with BRL-CAD to intersect a single ray with the displayed objects. By default, nirt is run using the current database and the currently displayed objects and uses the current eye point as the ray start point and the current viewing direction as the ray direction. This effectively fires a ray at the center of the MGED display. The resulting list of intersections between the ray and the objects is given. Additional arguments may be supplied on the nirt command line. See the man page of nirt for more details.

The quit command ends the MGED process. Note that there is no write database command in MGED. All changes are made to the database as the user performs them. Therefore, a quit command will not restore the database to its pre-edited state. This is a synonym for the q command.

qvrot dx dy dz angle

The qvrot command adjusts the current MGED viewing direction such that the eye is positioned along the direction vector (dx dy dz) from the view center and is looking towards the view center. The angle (in degrees) allows for a twist about the viewing direction. The ae command provides a similar capability.

r region_name <operation object>

The r command creates a region with the specified region_name. The region is constructed using the list of Boolean operations and object pairs. The operators are represented by the single characters +, -, and u for intersection, subtraction, and union, respectively. The object associated with each operator may be a combination or a primitive shape. No parentheses or any grouping indication is allowed in the r command. The operator hierarchy for the r command has been established through the ancestry of BRL-CAD and does not conform to accepted standards (see the c command for a more standard implementation). Intersection and subtraction operations are performed first, proceeding left to right; then union operations are performed. BRL-CAD regions are special cases of BRL-CAD combinations and include special attributes. Default values for these attributes may be set using the regdef command. As new regions are built, the default ident number gets incremented. If region_name already exists, then the operation/object pairs get appended to its end.

rcodes file_name

The rcodes command reads the specified file and assigns the region attributes to the regions listed. The file is expected to be in the format produced by the wcodes command.

rcc-blend rccname newname thickness [b|t]

The rcc-blend command generates a blend at an end (base [b] or top [t]) of the specified RCC shape. The thickness is the radius of the TOR curvature. The blend is saved as a region made up of an RCC and a TOR. The default end is the base.

rcc-cap rccname newname [height] [b|t]

The rcc-cap command is used to round the end of a cylinder with an ellipsoid. It creates an ELL shape with the given height at one end (base [b] or top [t]) of the specified RCC. If the height option is not specified, a spherical cap will be generated. The default end is the base.

rcc-tgc rccname newname x y z [b|t]

The rcc-tgc command creates a TGC shape with the specified apex (x y z) at one end (base [b] or top [t]) of the specified RCC. The default end is the base.

rcc-tor rccname newname

The rcc-tor command is used to round the edges of the specified RCC by creating a torus based on the parameters of that RCC. The radius values of the RCC must be greater than half its height.

red combination

The red command creates a file describing the specified combination and starts an editor for the user to modify the combination. The environment EDITOR variable will be used to select the editor. If EDITOR is not set, then /bin/ed will be used. All the attributes of BRL-CAD regions and combinations may be edited in this way. The region specific attributes will be ignored if the combination is not a region and is not set to be a region during editing. It is not necessary to be in an editing mode to run this command. The rm, r, comb, c, and g commands provide some basic combination editing capabilities.

The refresh command updates the MGED display.

regdebug [debug_level]

The regdebug command with no options toggles the display manager debug flag. If a debug_level is supplied, then the display manager debug flag is set to that value.

regdef item [air [los [material_code]]]

The regdef command sets the default region attributes used by the r and c commands when building a BRL-CAD region. The default ident number is incremented each time a new region is created with the r or c commands.

regions output_file <objects>

The regions command creates a summary of all the regions in the specified list of objects. The summary is written in the specified output_file. The summary includes, for each region, a sequential region number, its ident, air code, material code, los, the path from one of the objects to the region, and the Boolean formula for the region.

release [name]

The release command is used to close a display manager. If invoked with no arguments, the current display manager is closed. Otherwise, name (i.e., the Tcl/Tk path name of the display manager window) is closed.

The rfarb command creates a new ARB8 shape based on rotation and fallback angles. The command prompts the user for all the required information. In addition to the name for the new shape and the rotation and fallback angles, the user is prompted for the coordinates of one corner of the ARB8 and for two of the three coordinates of the other three vertices of one face of the ARB8. The other coordinate of each of these vertices is calculated in order to ensure that the face is planar. The user is then prompted for a thickness, and the first face is extruded normally by the specified thickness to complete the ARB8.

rm combination <members>

The rm command deletes all occurrences of the listed members from the specified combination. The red, r, comb, c, and g commands provide other combination editing capabilities.

rmater file

The rmater command reads the specified file and sets the combination shader, color, and inheritance values according to those listed in the file. The format of the file is expected to be as produced by the wmater command.