Table of Contents
_________________________________________________________________
wdb_open - create and manipulate a database object.
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]
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.
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 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.
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}
Mark L. Ulferts <mulferts@austin.dsccc.com>
Basic layout for documenting classes.
Robert G. Parker
Table of Contents