Drawable Geometry Object Documentation

Table of Contents

_________________________________________________________________

## NAME

dg_open - create and manipulate a drawable geometry object.

## SYNOPSIS

dg_open [dgName dbName]

## DESCRIPTION

The dg_open command creates a new drawable geometry object (given by the dgName argument) and is associated with the database object (given by the dbName argument). The dg_open command returns its dgName argument. At the time this command is invoked, there must not exist a drawable geometry object named dgName.

## METHODS

The dg_open command creates a new Tcl command whose name is dgName. This command may be used to invoke various operations on the drawable geometry object. It has the following general form:

dgName option ?arg arg ...?

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

dgName assoc [dbName]
  The drawable geometry object is associated with a database object. If dbName is specified, associate this drawable geometry object with dbName. Otherwise, return the associated database object.

dgName blast [-C#/#/#] <objects>
  Clear the display list of objects, then populate the list with the objects provided in the parameter list. Equivalent to the zap 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.

dgName clear
  Clear/empty the display list. This is the same as zap.

dgName close
  Close/destroy this drawable geometry object.

dgName draw [-C#/#/#] <objects>
  Add <objects> to the display list. 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.

dgName erase <objects>
  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 BRLCAD database itself. To actually remove objects from the database, use the kill command.

dgName erase -r <objects>
  Delete the specified list of objects from the display list. This command will allow the user to delete objects that have not been explicitly displayed (unlike the erase command). Note that this has no effect on the BRLCAD database itself. To actually remove objects from the database, use the kill command.

dgName ev [-dnqstuvwT] [-P #] <objects>
  Evaluate the objects specified by tessellating all primitive solids in the objects and then performing any Boolean operations specified in the objects. The result is then added to the display list according to the specified options:
  - d -- do not perform Boolean operations or any checking
  - w -- draw wireframes (rather than polygons)
  - n -- draw surface normals as little 'hairs'
  - s -- draw solid lines only (no dotdash for subtract and intersect)
  - t -- perform CSGtotNURBS conversion (still under development)
  - v -- shade using pervertex normals, when present
  - u -- draw NMG edgeuses (for debugging)
  - S -- draw tNURBS with trimming curves only, no surfaces
  - T -- do not triangulate (may produce unexpected results if not used with the w option

dgName get_autoview
  Return the view parameters (i.e. center and size) for optimal viewing (i.e. centered on the geometry with the smallest view size such that all geometry is still visible).

dgName headSolid
  Return the head solid pointer.

dgName illum object(s)
  Illuminate/highlight the specified object(s).

dgName label
  Not ready yet.

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

  dgName 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 display list changes. Otherwise, the observer is expected to have an update method which is called with the name of this drawable geometry object as an argument.

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

  dgName observer show
    Return the list of observers for this drawable geometry object.

dgName overlay plot_file [name]
  Plot the specified UNIX plot_file in the display list. Phony object names are created for each part of the plot file that is unique in 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.

dgName report [level]
  Report all the primitive solids currently drawn. The level determines how much detail should be included in the list. For level zero (the default), only a list of paths to solids in the display list is produced with an indication of whether they are being illuminated/highlighted. If level is greater than zero, the center, size, ident number, RGB color assigned to the region, and the actual color used to draw the solid are also listed. If level is greater than one, the number of vlist structures and the number of points in each vlist structure are also listed for each solid. If level is greater than two, then the actual lines drawn for each solid are also listed. The who command performs a similar function, but lists only the top level objects that are displayed. Going in the other direction, if level is -1, only a list of paths to solids in the display list is produced with no indication of whether they are being illuminated. If level is less than -1, only the leaves are printed.

dgName rt view_obj [options] [-- objects]
  Execute the BRLCAD rt program with the default options of ``-s50 -M''. The current database name is added to the end of the rt command line along with either the specified objects or, if none is specified, the list of currently displayed objects. The rt program is written such that options may be repeated, and the last occurrence of an option will override any earlier occurrences. This allows the user to specify other size (-s) options. The -M option tells rt to read the viewing parameters from standard input so that rays are only fired from the view specified by view_obj. See the man page on rt for details.

dgName rtcheck view_obj [options]
  Execute the BRLCAD rtcheck program with the default options of ``-s50 -M''. The -M option tells rtcheck to read the viewing parameters from standard input so that rays are only fired from the view specified by view_obj. The current database name and the list of currently displayed objects are added to the end of the rtcheck command line. The rtcheck program is written such that options may be repeated, and the last occurrence of an option will override any earlier occurrences. This allows the user to specify other size (-s) options. The rtcheck program uses raytracing to check for overlapping regions in the list of objects passed on the command line. Any discovered overlaps along a ray are represented as yellow lines that extend only in the areas of overlap. Details and a count of overlaps are also reported. Note that overlaps of less than 0.1 mm are currently ignored by rtcheck. The default option of -s50 indicates that the checking rays should be fired from a uniform square grid with 50 rays on a side. This is very coarse and may miss significant overlaps. It is recommended that the user select appropriate options for the rtcheck program and execute it for a variety viewing aspects to perform a thorough check. The granularity of the grid may be controlled with the -s, -w, -n, -g, and -G options. See the man page on rtcheck for details.

dgName vdraw command [args]
  This command allows the user to draw lines and polygons (optionally with per vertex normals) in the display list. Vdraw is used to build a named list of drawing commands, send the command list to the display list, modify the command list, or delete all or part of the command list. All vertices in the vdraw command are in millimeters. The drawing commands are represented by integers in the vdraw command. The drawing commands and the integers that vdraw uses for them are:

  MGED Drawing Command | Vdraw integer | MGED Action
  --- | --- | ---
  RT_VLIST_LINE_MOVE | 0 | begin a new line at this point
  RT_VLIST_LINE_DRAW | 1 | draw line from previous point to this point
  RT_VLIST_POLY_START | 2 | start polygon (argument is surface normal)
  RT_VLIST_POLY_MOVE | 3 | move to first polygon vertex
  RT_VLIST_POLY_DRAW | 4 | subsequent polygon vertices
  RT_VLIST_POLY_END | 5 | last vertex of polygon (should be same as first)
  RT_VLIST_POLY_VERTNORM | 6 | vertex normal (for shading interpolation)

  The vdraw commands are:
  - open -- with no arguments, this returns ``1'' if there is an open list, ``0'' otherwise. If an argument is supplied, a command list is opened with the provided name.
  - write -- with arguments of i c x y z, the mged drawing command #c is placed in the ith position of the command list. with a vertex of (x y z).
    -- with arguments of next c x y z, the command is placed at the end of the list.
  - insert -- with arguments of i c x y z, the mged drawing command #c is inserted just before the ith position of the command list.
  - delete -- with an integer argument of i, the ith command is deleted.
    -- with an argument of ``last'', the last command on the list is deleted.
    -- with an argument of ``all'', all the commands on the list are deleted.
  - params -- with an argument of color rrggbb, the color of all objects on this list is set. The rrggbb is a hex number representing the color, ``ffffff'' is white, ``ff0000'' is red, ``00ff00'' is green, ...
    -- with a single string argument, the name of the current list is changed.
  - read -- with an integer argument of i, the ith command is returned.
    -- with an argument of ``color'', the current color is returned.
    -- with an argument of ``length'', the number of commands in the current list is returned.
    -- with an argument of ``name'', the name of the current command list is returned.
  - show -- send the current command list to the display list.
  - vlist -- with an argument of ``list'', return a list of the names of all existing command lists.
    -- with an argument of delete list_name, delete the specified command list.
  All textual arguments may be abbreviated by their first letter.

dgName who [real | phony | both]
  List the top-level objects that are currently displayed. The phony flag asks for just phony objects. Phony objects are typically objects that are drawn in the display list, but are not actual database objects. Some phony objects are drawings from the vdraw command and the edgeuses drawn by the ev -u command. The real flag asks for just real objects, and the both flag asks for both real and phony objects. The default is just real objects. Any of the flags may be abbreviated by its first letter.

dgName zap
  Clear/empty the display list. This is the same as clear.

## EXAMPLE

The following sequence creates a database object and a drawable geometry object. And then draws some geometry from the associated database object.

cwish> wdb_open db moss moss.g
moss
cwish> dg_open dg moss
dg
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> dg draw all.g
cwish> dg who
all.g
cwish> dg zap
cwish> dg who
cwish> dg

## 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