Database Object Documentation

Table of Contents

_________________________________________________________________

## NAME

wdb_open - create and manipulate a database object.

## SYNOPSIS

wdb_open [dbName file dbFile]
wdb_open [dbName disk dbip]
wdb_open [dbName disk_append dbip]
wdb_open [dbName inmem dbip]
wdb_open [dbName inmem_append dbip]
wdb_open [dbName db dbFile]

## DESCRIPTION

The following describes opening a database object of type db:

Create a new database object (given by dbName) that is associated with the database file (given by dbFile). The wdb_open command returns its dbName argument. At the time this command is invoked, there must not exist a database object named dbName.

## METHODS

The wdb_open command creates a new Tcl command whose name is dbName. This command may be used to invoke various operations on the database object. It has the following general form:

dbName option ?arg arg ...?

Option and the args determine the exact behavior of the command. The following commands are possible for database objects:

dbName adjust object attribute1 new_value1 [attribute2 new_value2...]
  Modify object by adjusting the value of its attribute(s) to the new_value(s).

dbName c [-g|r] combination_name [Boolean_expression]
  Create a BRLCAD combination with the name combination_name. The -g option is the default and indicates that the combination should be flagged as a BRLCAD group and the -r option indicates that the combination is a BRLCAD 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. With no Boolean_expression and when combination_name does not already exist, a new empty combination will be created. If no Boolean_expression is provided, and combination_name does already exist and one of -g or -r is specified, then combination_name is flagged to agree with the indicated option. If a new region is created 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.

dbName cat <objects>
  Return a brief description of each item in the list of objects. If the item is a primitive solid, the type of solid and its vertex are displayed. If the item is a combination, the Boolean formula for that combination is displayed including operands, operators, and parentheses. If the combination is flagged as a region, then that fact is also displayed along with the regions ident code, air code, los, and GIFT material code.

dbName close
  Close/destroy the database object.

dbName color low high r g b str
  Create 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 r g b 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 when drawing wireframe.

dbName comb combination_name <operation object>
  Create a new combination or extend 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.

dbName concat database_file [prefix]
  Concatenates an existing BRLCAD database to the database currently being edited. If a prefix is supplied, then all objects from the database_file will have prefix added to the beginning of their names. Note that each BRLCAD object must have a unique name, so care must be taken not to concat 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 concatenation process, 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).

dbName cp from_object to_object
  Make a duplicate of an object (solid or combination). If from_object is a solid, then it is simply copied to a new solid 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.

dbName dbip
  Return the database instance pointer associated with this database object.

dbName dump dbfile
  Write the current state of the database to dbfile.

dbName dup file [prefix]
  Check the specified file (which is expected to contain a BRLCAD 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 concat command to insure that there are no name clashes.

dbName expand regexp
  Perform matching of the regular expression, regexp, with the names of all the objects in the database returning all those that successfully match.

dbName find <objects>
  Return all combinations that have any of the objects specified as a member.

dbName form
  Return the format used to display objects of the specified type.

dbName g groupname <objects>
  Create 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.

dbName get object [attribute]
  Return information about the database object. If object is a path, the transformation matrices encountered along the path will be accumulated and applied to the leaf before returning the information. If no attribute is specified, all the details about object are returned. If a specific attribute is listed, then only that information is returned.

dbName i obj_name comb_name [operation]
x
  Add 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.

dbName keep keep_file <objects>
  Copy 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 BRLCAD database file. The objects in the list must exist in the current database.

dbName kill [-f] <objects>
  Delete 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.

dbName killall <objects>
  Delete the specified objects from the current database and remove 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.

dbName killtree <objects>
  Delete the specified objects from the current database and recursively delete all objects referenced by any of those objects. If one of the objects listed is a combination, then that combination will be deleted as well as any objects that are members of that combination. If a member of that combination is itself a combination, then all its members will also be destroyed. This continues recursively until the primitive solids 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.

dbName l [-r] <objects>
  Return 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 solids, detailed solid 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 solid, then all possible paths from that point down to individual solids will be considered. The solid at the end of each possible path will be listed with its parameters adjusted by the accumulated transformation.

dbName 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 solid represents that primitive solid with the transformations accumulated through the path applied to it. The ``listeval'' command displays primitive solid parameters after applying the accumulated transformations from the indicated path. If the specified path does not end at a primitive solid, then all possible paths from the indicated path to any primitive solid will be evaluated and displayed.

dbName ls [-a -c -r -s] [objects]
  With no object arguments, list the name of every object in the database (in alphabetical order). If the object argument is supplied, only those objects are listed. The following options are also allowed:
  - a - list all objects in the database
  - c - list all combinations in the database
  - r - list all regions in the database
  - s - list all solids in the database
  Note - when any of the above options are used, the output is not formatted.

dbName match regexp1 [regexp2 regexp3...]
  Return a list of all objects in the database that match the list of regular expressions.

dbName mv old_name new_name
  Change 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 objects name everywhere.

dbName mvall old_name new_name<
  Change 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 objects name without changing references to it. The prefix command will also change the names and references of objects.

dbName observer [subcommand]
  This command is used to maintain a list of observers. Observers are objects who have registered an interest in this database object and are notified when the database changes (i.e. create/destroy geometry objects).

  dbName observer attach obs [command]
    Add the specified observer, obs, to the list of observers. If command is specified then it is executed each time the database changes. Otherwise, the observer is expected to have an update method which is called with the name of this database object as an argument.

  dbName observer detach obs
    Remove the specified observer, obs, from the list of observers.

  dbName observer show
    Return the list of observers for this database object.

dbName open [dbfile]
  Close the current database file and open dbfile. If dbfile is not found or cannot be created, the current database is left open. If dbfile is not specified on the command line, the name of the current database file is returned.

dbName paths path_start
  List all existing paths that start from the specified path_start and end at a primitive solid. The path_start may be specified by ``/'' separated components or they may be separated by spaces (but not both).

dbName prcolor
  List 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 when drawing wireframe.

dbName pull <objects>
  Pulls the effects of all transformation matrices that appear in the primitive solids in the trees to the specified objects head up the tree. This will restore the parameters of the primitive solids if any of the transformation matrices are present. All the transformation matrices visited will correspond to the current matrix transformation for that node. This command will fail, and no changes will be made, if any primitive solid referenced as the list of objects.

dbName push <objects>
  Force the effects of all transformation matrices that appear in any combinations in the trees from the specified objects down to the primitive solids. This will change the parameters of the primitive solids 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 solid 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 solids are multiply referenced.

dbName put object type attributes
  Create the database object of the specified type with the specified attributes. The arguments to the put command are the same as those returned by the get command. Type can be any of the solid types or comb.

dbName r region_name <operation object>
  Create a region with the specified region_name. The region is constructed using the list of Boolean operation 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 solid. 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 BRLCAD, 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. BRLCAD regions are special cases of BRLCAD 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.

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

dbName rt_gettrees rtproc tree1 [tree2 tree3...]
  Create a ray-tracing object named rtproc. See the documentation of the raytrace object for details on how to use the ray-tracing object.

dbName title [string]
  Set/get the database title string. If any command line arguments are supplied, they will become the new title string for the current database. Quote marks must be doubly escaped. If no arguments are provided the current database title is returned.

dbName tol [abs #] [rel #] [norm #] [dist #] [perp #]
  With no arguments, list the current tolerance settings. If the command line includes any of the keywords followed by a number, then that tolerance setting will be modified. The keywords are:
  - Tessellation tolerances:
    The tessellation tolerances are used to control the facetization of primitive solids. If more than one tolerance value is specified, the tessellation is performed to meet the most stringent.
  - abs -- This absolute tolerance is specified in model units and represents the maximum allowable error in the distance from the actual solid surface to the tessellated surface. An absolute tolerance of 0 means that the absolute tolerance should be ignored.
  - rel -- This relative tolerance is specified in terms of a fraction of the solid size. The value is multiplied by the size of the solid to determine another bound on the maximum allowable error in the distance from the actual solid surface to the tessellated surface. An relative tolerance of 0 means that the relative tolerance should be ignored.
  - norm -- This normal tolerance is specified in degrees and represents the maximum angle between the actual solid surface normal and the tessellated surface normal. A normal tolerance of 0 means that the normal tolerance should be ignored.
  - Calculational tolerances:
    The calculational tolerances are used in evaluating the Boolean operations specified in a combination. This is used, for example, in the ev, facetize, and bev commands.
  - dist -- The distance tolerance is specified in model units and represents the minimum distance required between two vertices to consider them distinct.
  - perp -- The perpendicularity tolerance is specified as the cosine of an angle. Two objects will be considered perpendicular if the cosine of the angle between them is less than the perpendicularity tolerance. Similarly, two objects will be considered parallel if the cosine of the angle between them is greater than 1.0 - the perpendicularity tolerance.

dbName tops
  Return a list of all the top level objects in the current database. The top level objects are all those objects that are not referenced by some other combination. The hierarchical structure of BRLCAD databases usually means that there will be a top level object that includes all (or at least most) of the objects in the database.

dbName tree <objects>
  List the contents of the specified objects in a tree-like format that displays the hierarchical structure of the objects, and all objects referenced by them, down to the primitive solid level.

dbName whatid region
  List the ident number of the specified region.

dbName whichair <air_codes>
  List all the regions that use one of the air_codes specified. Regions that have non-zero ident numbers will not be listed by this command.

dbName whichid <idents>
  List all the regions that use one of the idents specified.

## EXAMPLE

The following sequence creates a database object and uses it to query the database.

cwish> wdb_open db moss moss.g
moss
cwish> moss ls

    LIGHT               cone.r/R            light.r/R           tor.r/R
    all.g/              cone.s              platform.r/R
    box.r/R             ellipse.r/R         platform.s
    box.s               ellipse.s           tor

cwish> moss tops
all.g
cwish> moss l all.g

    all.g:  --
       u platform.r
       u box.r [-23.6989,13.41,8.02399]
       u cone.r [22.0492,12.2349,2.11125e-07]
       u ellipse.r [14.6793,-41.6077,38.7988]
       u tor.r
       u light.r

cwish> moss l tor.r

    tor.r:  REGION id=6000  (air=0, los=0, GIFTmater=0) --
    Color 240 240 0
       u tor

cwish> moss get tor
tor V {4.91623592376708984375 -32.8022308349609375 31.7117767333984375} H {0 1 0} r_a 25.399997711181640625 r_h 5.0799999237060546875
cwish> moss adjust tor H {1 0 0}

## ACKNOWLEDGMENTS:

Mark L. Ulferts <mulferts@austin.dsccc.com>

            Basic layout for documenting classes.

## AUTHOR

Robert G. Parker

Table of Contents

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- EXAMPLE
- ACKNOWLEDGMENTS
- AUTHOR