LIBWDB(3)

NAME
libwdb - library for procedural generation of MGED databases

SYNOPSIS
#include ``machine.h''
#include ``vmath.h''
#include ``wdb.h''

mk_id( fp, title )
FILE	*fp;
char	*title;

mk_half( fp, name, norm, d )
FILE	*fp;
char	*name;
double	d;
point_t	norm;

mk_rpp( fp, name, min, max )
FILE	*fp;
char	*name;
point_t	min, max;

mk_wedge( fp, name, vert, xdir, zdir, xlen, ylen, zlen, x_top_len );
FILE	*fp;
char	*name;
point_t	vert;
vect_t	xdir;
vect_t	zdir;
fastf_t	xlen;
fastf_t	ylen;
fastf_t	zlen;
fastf_t	x_top_len;

mk_arb4( fp, name, pts )
FILE	*fp;
char	*name;
point_t	pts[];

mk_arb8( fp, name, pts )
FILE	*fp;
char	*name;
point_t	pts[];

mk_sph( fp, name, center, radius )
FILE	*fp;
char	*name;
point_t	center;
fastf_t	radius;

mk_ell( fp, name, center, a, b, c )
FILE	*fp;
char	*name;
point_t	center;
vect_t	a, b, c;

mk_tgc( fp, name, center, a, b, c, d )
FILE	*fp;
char	*name;
point_t	center;
vect_t	a, b, c, d;

mk_tor( fp, name, center, n, r1, r2 )
FILE	*fp;
char	*name;
point_t	center;
vect_t	n;
double	r1, r2;

mk_cone( fp, name, base, dir, height, rad1, rad2 )
FILE	*fp;
char	*name;
point_t	base;
vect_t	dir;
fastf_t	height;
fastf_t	rad1;
fastf_t	rad2;

mk_rcc( fp, name, base, height, radius )
FILE	*fp;
char	*name;
point_t	base;
vect_t	height;
fastf_t	radius;

mk_pipe( fp, name headp )
FILE	*fp;
char	*name;
struct wdb_pipept *headp;

mk_pipe_free( headp )
struct wdb_pipept	*headp;

mk_pipe_init( headp, coord, od, id, bendradius )
struct wdb_pipept *headp;
point_t coord;
fastf_t od, id, bendradius;

mk_add_pipe_pt( headp, coord, od, id, bendradius )
struct wdb_pipept *headp;
point_t coord;
fastf_t od, id, bendradius;

mk_comb( fp, name, len, region, matname, matparm, rgb, inherit )
FILE	*fp;
char	*name;
char	*matname;
char	*matparm;
char	*rgb;

mk_fcomb( fp, name, len, region )
FILE	*fp;
char	*name;

mk_memb( fp, name, mat, op )
FILE	*fp;
char	*name;
mat_t	mat;
int	op;

mk_addmember( name, headp, mat, op )
char	*name;
struct	wmember *headp;
mat_t mat;
int	op;

mk_lcomb( fp, name, headp, region, matname, matparm, rgb, inherit )
FILE	*fp;
char	*name;
struct	wmember *headp;
char	*matname;
char	*matparm;
char	*rgb;

mk_lfcomb( fp, name, headp, region )
FILE	*fp;
char	*name;
struct	wmember *headp;

mk_polysolid( fp, name )
FILE	*fp;
char	*name;

mk_poly( fp, npts, vert, norm )
FILE	*fp;
int	npts;
fastf_t	vert[][3];
fastf_t	norm[][3];

mk_fpoly( fp, npts, vert )
FILE	*fp;
int	npts;
fastf_t	vert[][3];

mk_bsolid( fp, name, nsurf, res )
FILE    *fp;
char    *name;
int     nsurf;
double  res;

mk_bsurf( filep, bp )
FILE    *filep;
struct b_spline *bp;

DESCRIPTION
This library exists to permit writing MGED databases from arbitrary procedures. Some of the high-level structure of MGED databases (eg, that they start with an ID record, and that COMB records must be followed immediately by MEMBER records) is currently implicit in the calling routines. This library is by no means complete, and routines for writing every type of solid do not yet exist. While it is expected that this library will grow and change as experience is gained, it is not clear what direction that evolution will take. Be prepared for changes in the interface to some of these routines in future releases. All routines take as their first argument the stdio FILE pointer (eg, stdout) on which the generated MGED database record(s) will be written with fwrite().

mk_id fwrites an IDENT record on the indicated stdio file, with the string title associated. Note that to have a valid database, the the first record written must have been an IDENT record such as written by this routine.

mk_half makes a halfspace with name ``name''. It is specified by the distance ``d'' from the origin, and the outward pointing normal vector ``norm''.

mk_rpp makes an ARB8 called ``name'' specified as a right rectangular parallelepiped in terms of a minimum point ``min'' and a maximum point ``max''.

mk_wedge makes a right angular wedge called ``name'' specified by a starting vertex located in the lower left corner of the solid, an x-direction vector, a z-direction vector, an x-length, a y-length, a z-length, and a top x-length. The y-direction vector is the result of x-direction vector cross z-direction vector. All vertices are make in the counterclockwise direction, bottom face first. The top face is made by extruding the bottom face in the z direction.

mk_arb4 makes an ARB8 called ``name'' described as an ARB4, ie, by 4 points, the first 3 of which lie on a plane, and the fourth is the ``peak''.

mk_arb8 makes an ARB8 called ``name'' described by an array of 8 points in ``pts''. All plates with 4 points must be co-planar. If there are degeneracies (ie, all 8 vertices are not distinct), then certain requirements must be met. If we think of the ARB8 as having a top and a bottom plate, the first four points listed must lie on one plate, and the second four points listed must lie on the other plate.

mk_sph makes a spherical ellipsoid called ``name'' centered at point ``center'' with radius ``radius''. mk_ell makes an ellipsoid called ``name'' centered at point ``center'' with three perpendicular radius vectors. The eccentricity of the ellipsoid is controlled by the relative lengths of the three radius vectors.

mk_tgc makes a truncated general cone called ``name'' with the base plate centered at ``center'' and a height vector ``height'', which is perpendicular to the two end plates. The length of the height vector defines the location of the top plate. The vectors ``a'' and ``b'' are the base radius vectors, and the vectors ``c'' and ``d'' are the nose vectors.

mk_tor makes a torus called ``name'' centered at point ``center'', with the torus lying in a plane with normal ``n''. Radius ``r1'' is the distance from the center point of the torus to the center of the solid part, and radius ``f2'' is the radius of the solid part.

mk_cone makes a right circular cone called ``name'' specified by the center point of the base, a direction or height vector, a height scalar, and a radius for each end of the cone. The direction vector is unitized and serves to derive a vector ``a'', which is orthogonal to the direction vector and itself. This vector is scaled by both radii to obtain two of four vectors required to make a cone. It is then crossed with the unitized direction vector, and the result thereof is scaled by both radii as well to obtain the last of four vectors needed to make a cone.

mk_rcc makes a truncated general cone (TGC) with name ``name'' specified as a right circular cylinder. The base plate of the cylinder is centered at ``base'', with height vector ``height'' which is perpendicular to the two end plates, the length of which defines the location of the top plate. The radius given as ``radius'' defines the size of the end plates.

mk_pipe creates a ``pipe'' solid with the specified ``name'' and writes it to the file ``fp''. The user must provide a linked list of ``pipe'' segments headed by ``headp''. Each pipe segment includes fields indicating a ``control'' point for the pipe, an inner diameter, an outer diameter and a bend radius. The inner diameter must be less than the outer diameter, and a zero innner diameter creates a solid wire rather than a hollow pipe. The pipe is constructed along straight lines through successive points, with circular bends (of the indicated radius) connecting the straight sections. The bend radius must be greater than the outer radius. The user is responsible for freeing the memory used by the list of pipe segments (see mk_pipe_free() below.

mk_pipe_free will free the memory used by a linked list of pipe segments. This does not free the list head.

mk_pipe_init initializes a linked list of pipe segments with the initial point, inside diameter, outside diameter, and bend radius.

mk_add_pipe_pt adds another pipe segment to the list with the indicated point, outside radius, inside radius, and bend radius.

mk_comb defines a combination of name ``name'', with material properties information included. ``len'' indicated the number of mk_memb calls (MEMB records) that will immediately follow. ``region'' is a boolean that is set to mark this combination as a region. ``matname'' is either a NULL pointer, or a pointer to a string containing the material property name. ``matparm'' is either a NULL pointer, or a pointer to a string containing the material property parameter information, which is material-specific (and still experimental). Color is passed as an array of three unsigned chars in ``rgb''. Color ``inherit'' is a boolean, and if true, the color and material properties will be passed from upper-level objects to lower-level objects. mk_fcomb makes a simple combination header, with name ``name'', length ``len'', and the boolean ``region''. It functions just like mk_comb. ``len'' mk_memb calls must immediately follow the call to mk_comb or mk_fcomb. Each call to mk_memb adds a reference to object ``name'' to the combination. It is transformed by the 4x4 matrix ``mat'', and is combined by boolean operation ``op'', chosen from the list of: UNION, INTERSECT, SUBTRACT, from <brlcad/db.h>.

mk_addmember is used to obtain dynamic storage for a new wmember structure (see wdb.h ). Then mk_lcomb can be used in the same way as mk_comb to make a combination of a linked list of wmember structures. This is the only recommended way to create combinations, because it collects up the details in memory, and produces the combination and member records all at once, rather than in multiple calls, as in mk_comb and mk_memb. The ``op'' argument must be one of WMOP_UNION, WMOP_SUBTRACT, or WMOP_INTERSECT. In the future, mk_comb and mk_memb will no longer be supported. mk_lfcomb is the linked list equivalent of mk_fcomb. Note that the linked list heads must be initialized by an invocation of BU_LIST_INIT( &head.l );

mk_polysolid writes the header record for a polygon solid called ``name'', which must be immediately followed by one or more mk_poly calls before using any other mk_* routines. mk_poly is called with ``npts'' (3 to 5) vertices in the ``vert'' array, with a matching number of normals in the ``norm'' array. All vertices must be coplanar. For the present, note that librt/pg.c only uses the first normal in the ``norm'' array, although the intention is to do optional normal interpolation for those occasions where it may be desirable to have curved-looking polygons. mk_fpoly is like mk_poly except no normals are given. It is a ``fast'' or ``flat'' form of the poly routine. This function computes normals for you from the given vertices by assuming a counter clockwise ordering of the vertices as viewed from the top (outside).

The routine mk_bsolid writes the header for a b-spline solid ``name'', with ``nsurf'' surfaces, at ``res'' resolution. This call must be followed by ``nsurf'' calls to mk_bsurf which enters the respective surfaces into the combination. This pair work much like the mk_comb and mk_memb pair.

The global variable mk_version may be set to 4 or 5, depending on which format BRL-CAD database you wish to write. By default, the most recent version is always created.

EXAMPLE(S)

Several examples of how to use this library can be found in the proc-db directory of the BRL-CAD source distribution.

SEE ALSO
brlcad(1B), mged(1B), rt(1B)

DIAGNOSTICS
None

AUTHOR(S)
Michael John Muuss
Paul R. Stay

BUGS
The library is incomplete. The need for the application to know higher-level details is unfortunate, but necessary to keep the library simple. We may pay for this later.

SOURCE
 SECAD/VLD Computing Consortium, Bldg 394
 The U. S. Army Ballistic Research Laboratory
 Aberdeen Proving Ground, Maryland 21005

COPYRIGHT
This software is Copyright (c) 1987-2007 United States Government as represented by the U.S. Army Research Laboratory. All rights reserved.

BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>.