Difference between revisions of "BRL-CAD Primitives"

From BRL-CAD
(Arbitrary convex polyhedra: developed box subsection of arb section)
(Arbitrary convex polyhedra: moved creation discussions to a separate article, and finished this section as an overview of arb primitives)
Line 14: Line 14:
 
= Arbitrary convex polyhedra =
 
= Arbitrary convex polyhedra =
  
An '''arbitrary convex polyhedron''' ('''arb''') is a geometric solid that is completely enclosed by a set of 3-dimensional planes. Each has a set of straight-edged, flat faces/facets defined by those planes and their intersections. For example, a rectangular parallelpiped (rpp) is enclosed by six planes--two perpendicular/normal to the X-axis, two normal to the Y-axis, and two normal to the Z-axis.
+
An '''arbitrary convex polyhedron''' ('''arb''') is a geometric volume that is completely enclosed by a set of 3-dimensional planes. Each has a set of straight-edged, flat '''faces''' outlined by the intersections of those planes. The intersection of each pair of planes is a line whose intersections with other planes defines a pair of '''vertices'''. The line segment between those two vertices is an '''edge''' of the polyhedron that is shared by two faces. Each vertex is common to an equal number (at least three) of faces and edges.
  
The BRL-CAD geometry file format defines two types of arb object records:
+
For example, a rectangular parallelepiped is enclosed by three orthagonal pairs of parallel planes. Their intersections define six faces, each with four edges and four vertices. There are a total of 12 edges (each shared by two faces) and 8 vertices (each shared by three faces and three edges).
* '''arb8'''s are specified by a set of eight vertices (V1 through V8) that collectively define up to six facets.
 
* '''arbn'''s are specified by a set of intersecting planes, each defined by four coefficients.
 
  
Although any arb object could be defined and stored as an arbn, the arb8 record type is used to store all of the special-case arbs discussed below (that is, all except the explicitly arbn type).
+
The BRL-CAD geometry file format defines two types of records for such polyhedra:
 +
* [[#ARB8 Records|'''arb8'''s]] are specified by a set of eight vertices.
 +
* [[#ARBN Records|'''arbn'''s]] are specified by a set of intersecting planes, each defined by four coefficients.
  
'''See also:''' [[Creating and editing arbs]]
+
Although any polyhedron can be defined and stored as an arbn, the arb8 record type is more commonly employed because it is simpler to work with and still accommodates most constructive solid geometry applications.
  
== Box ==
+
== ARB8 Records ==
  
Each '''box''' is enclosed by three pairs of parallel planes defined by a vertex [an (Xv,Yv,Zv) vector relative to the origin] and depth, width and height vectors [(Xd,Yd,Zd), (Xw,Yw,Zw), (Xh,Yh,Zh)]. Those vectors not only do not have to be normal to the X, Y and Z axes, they need not even be orthogonal (mutually perpendicular to each other). Thus, those vectors merely define the box's opposing faces as pairs of similar parallelograms. If they are parallel to the X, Y, Z axes, the box will have the same characteristics as an rpp (see [[#Rectangular parallelpiped (rpp)|below]]).
+
An '''arb8''' record is specified by a set of eight {X, Y, Z} vertices designated V1 through V8, which need not all be unique. As discussed in the [[Creating and editing arb8 primitives]] article, BRL-CAD uses such records to represent polyhedra having four, five or six faces:
  
[[Image:ExampleBoxThumb.png|right]]
+
* '''arb8''' shapes represent '''hexahedra''' (six-sided polyhedra) whose sides are all quadrilaterals. They thus have eight edges and eight unique vertices. In addition to simply specifying the {X, Y, Z} coordinates of those vertices, MGED provides easier ways to create the following specific types of hexahedra:
 +
** '''3ptarb''' shapes represent '''right quadrilateral prisms''', which are extruded quadrilaterals having parallel ends connected by four rectangular sides.
 +
** '''box''' shapes represent '''parallelepipeds''', whose faces comprise three pairs of equal parallelograms. Unlike a common box, those faces need not be rectangular—if they are, the enclosed volume is a rectangular parallelepiped.
 +
** '''rpp''' shapes represent '''rectangular parallelepipeds''' (also known as '''cuboids''' and '''rectangular prisms'''), whose faces comprise three pairs of equal rectangles. If one pair of faces are squares, the volume is a '''square prism'''. If all of them are squares, the volume is a '''cube''' (geometrically, there cannot be just two pairs of square faces).
  
Each box is stored as an arb8 record whose eight vertices are calculated from its defining vectors as:
+
* '''arb7''' shapes represent hexahedra with four quadrilateral and two triangular faces. They have a total of eleven edges with seven unique vertices, one of which is shared by the two triangular faces. They can only be created by specifying the {X, Y, Z} coordinates of those vertices.
# (X1, Y1, Z1) = (Xv, Yv, Zv)
 
# (X1+Xw, Y1+Yw, Z1+Zw) = (Xv+Xw, Yv+Yw, Zv+Zw)
 
# (X2+Xh, Y2+Yh, Z2+Zh) = (Xv+Xw+Xh, Yv+Yw+Yh, Zv+Zw+Zh)
 
# (X3-Xw, Y3-Yw, Z3-Zw) = (Xv+Xh, Yv+Yh, Zv+Zh)
 
# (X1+Xd, Y1+Yd, Z1+Zd) = (Xv+Xd, Yv+Yd, Zv+Zd)
 
# (X5+Xw, Y5+Yw, Z5+Zw) = (Xv+Xd+Xw, Yv+Xd+Yw, Zv+Zd+Zw)
 
# (X6+Xh, Y6+Yh, Z6+Zh) = (Xv+Xd+Xw+Xh, Yv+Xd+Yw+Yh, Zv+Zd+Zw+Zh)
 
# (X7-Xw, Y7-Yw, Z7-Zw) = (Xv+Xd+Xh, Yv+Xd+Yh, Zv+Zd+Zh)
 
  
== Rectangular parallelpiped (rpp) ==
+
* '''arb6''' shapes represent '''triangular prisms''' and '''truncated tetrahedra''', both of which have two triangular ends connected by three quadrilateral sides (its seems they should be called quintahedra but that term seems to be rarely used). Either has a total of nine edges with six unique vertices. In addition to simply specifying the {X, Y, Z} coordinates of their vertices, MGED provides an easier way to create one specific type of hexahedron:
 +
** '''raw''' ('''right angle wedge''') shapes are '''triangular prisms''' whose ends are parallel to each other. Interestingly enough, they don't have to incorporate any right angles. If the ends are perpendicular to the connecting edges, the shape is a '''right triangular prism''' with rectangular sides. Presumably two of the rectangular sides of an actual right-angle wedge would also be perpendicular to each other. Such a shape could easily be created as a BRL-CAD raw primitive.
  
Each '''rectangular parallelpiped''' ('''rpp''') is enclosed by two planes normal to the X-axis (mathematically defined by X=Xmin and X=Xmax), two normal to the Y-axis (Y=Ymin and Y=Ymax), and two normal to the Z-axis (Z=Zmin and Z=Zmax). The opposing faces of any such arb are thus pairs of similar rectangles. If Xmax-Xmin = Ymax-Ymin = Zmax-Zmin, as they are for the default rpp created by MGED's make and create commands, the resulting ppp would be a cube with edges parallel to the three axes.
+
* '''arb5''' shapes represent '''quadrahedra''', which are polyhedra with five faces—a quadrilateral base and the three triangular sides with a total of f. If such a volume has a rectangular base it is a '''rectangular pyramid''', one with a square base is a '''square pyramid'''.
  
[[Image:DefaultRppThumb.png|right]]
+
* '''arb4''' shapes represent tetrahedra, which are polyhedra with four triangular faces. If all four faces are equilateral triangles, the shape is a '''regular tetrahedron'''.
  
Each rpp is stored as an arb8 record whose eight vertices are calculated from its six planar coefficients as:
+
== ARBN Records ==
# (Xmax, Ymin, Zmin)
 
# (Xmax, Ymax, Zmin)
 
# (Xmax, Ymax, Zmax)
 
# (Xmax, Ymin, Zmax)
 
# (Xmin, Ymin, Zmin)
 
# (Xmin, Ymax, Zmin)
 
# (Xmin, Ymax, Zmax)
 
# (Xmin, Ymin, Zmax)
 
  
Note that the rpp primitive type is actually a special case of the box type. Thus, you can also create an rpp by specifying a box whose depth, width and height vectors are parallel to the X, Y and Z axes.
+
An '''arbn''' record is specified by N sets of intersecting planes, each defined by four coefficients:
 
+
* the {X, Y, Z} coefficients of the plane's normal vector pointing outward from the center of the arbn shape, and
== Right angle wedge (raw) ==
+
* the perpendicular distance of that plane from the origin.
 
+
As discussed in the [[Creating and editing arbn primitives]] article, BRL-CAD uses such primitives to represent polyhedra having any number of sides, edges and vertices.
Right Angle Wedge, special case of arb6
 
;Handled by: in form(arb8)
 
;Arguments: Vertex of first corner, direction vectors for height, width, and depth
 
 
 
== arb8 ==
 
 
 
Arbitrary straight-edged shape with 8 vertices.
 
 
 
;Handled by: make in form create
 
;Arguments: 8 Vertices in the following order: 1234 vertices for the front face, starting at bottom left, counterclockwise; then 5678 vertices for the rear face, starting at bottom left, counterclockwise.
 
;Example:
 
in unitcube.s arb8  0 0 0  1 0 0  1 0 1  0 0 1  0 1 0  1 1 0  1 1 1  0 1 1
 
creates the unit cube (first vertex at the origin, extends for 1 unit in x, y and z direction).
 
 
 
 
 
== arb7 ==
 
 
 
Special case of arb8, except with point 8 merged into point 5, making the left face triangular
 
;Handled by: make in form(arb8) create
 
 
 
 
 
== arb6 ==
 
 
 
Arbitrary straight-edged shape with 6 vertices, special case of arb8.
 
;Handled by: make in form(arb8) create
 
;Arguments: 6 Vertices in the following order: 1234 vertices for the front face, starting at bottom left, counterclockwise; then back edge is 5 on bottom, 6 on top.  Top and bottom faces are triangles.
 
;Example:
 
 
 
in arb6.s arb6 1 -1 -1  1 1 -1  1 1 1  1 -1 1  -1 0 -1  -1 0 1
 
 
 
 
 
== arb5 ==
 
 
 
special case of arb8.
 
;Handled by: make in form(arb8) create
 
 
 
 
 
== arb4 ==
 
 
 
special case of arb8.
 
;Handled by: make in form(arb8) create
 
 
 
 
 
== arbn ==
 
 
 
Arbitrary solid bounded by N planes. 
 
;The solid is constructed by N sets of plane coefficients and distance magnitudes, that define space which is ~outside~ the solid.  The coefficients define a vector whose normal is a plane parallel to the face of the solid.  The surface of the solid is at the perscribed distance along this vector. 
 
 
 
The distances may be negative and are used when a face lies on the opposite side of the origin as the tip of its vector.  An example is if the left side of a box lies on the positive X axis.  In this case, because the left side is being defined, the vector points left (coefficients -1 0 0), but since the point is on the positive X axis its distance is opposite its vector and therefore negative.
 
 
 
;Handled by: make in create
 
;Arguments
 
:Number of planes
 
:xyz direction vector and distance for each plane
 
 
 
;Example
 
:in arbn.s arbn 8  1 0 1 1  -1 0 0 1  0 1 0 1  0 -1 0 1  0 0 1 1  0 0 -1 1  0.5 0.5 0.5 1  -0.5 -0.5 -0.5 1
 
 
 
;Example with negative distance
 
:in arbn2.s arbn 6  1 0 0 100  -1 0 0 -10  0 1 0 200  0 -1 0 -10  0 0 -1 0  0 0 1 1.5
 
:...is equivalent to...
 
:in rpp.s rpp 10 100 10 200 0 1.5
 
  
 
=Ellipsoids=
 
=Ellipsoids=

Revision as of 00:18, 10 June 2013


This article provides an overview of various types of geometric primitive objects that can be added to a BRL-CAD geometry file. The shape, size, location and orientation of each such object are defined by a set of parameters/properties that are specific to its type, which are discussed in the corresponding section below.

For general discussions on using MGED to create primitive objects, view their properties, and modify or move them, see:

also see:

Arbitrary convex polyhedra

An arbitrary convex polyhedron (arb) is a geometric volume that is completely enclosed by a set of 3-dimensional planes. Each has a set of straight-edged, flat faces outlined by the intersections of those planes. The intersection of each pair of planes is a line whose intersections with other planes defines a pair of vertices. The line segment between those two vertices is an edge of the polyhedron that is shared by two faces. Each vertex is common to an equal number (at least three) of faces and edges.

For example, a rectangular parallelepiped is enclosed by three orthagonal pairs of parallel planes. Their intersections define six faces, each with four edges and four vertices. There are a total of 12 edges (each shared by two faces) and 8 vertices (each shared by three faces and three edges).

The BRL-CAD geometry file format defines two types of records for such polyhedra:

  • arb8s are specified by a set of eight vertices.
  • arbns are specified by a set of intersecting planes, each defined by four coefficients.

Although any polyhedron can be defined and stored as an arbn, the arb8 record type is more commonly employed because it is simpler to work with and still accommodates most constructive solid geometry applications.

ARB8 Records

An arb8 record is specified by a set of eight {X, Y, Z} vertices designated V1 through V8, which need not all be unique. As discussed in the Creating and editing arb8 primitives article, BRL-CAD uses such records to represent polyhedra having four, five or six faces:

  • arb8 shapes represent hexahedra (six-sided polyhedra) whose sides are all quadrilaterals. They thus have eight edges and eight unique vertices. In addition to simply specifying the {X, Y, Z} coordinates of those vertices, MGED provides easier ways to create the following specific types of hexahedra:
    • 3ptarb shapes represent right quadrilateral prisms, which are extruded quadrilaterals having parallel ends connected by four rectangular sides.
    • box shapes represent parallelepipeds, whose faces comprise three pairs of equal parallelograms. Unlike a common box, those faces need not be rectangular—if they are, the enclosed volume is a rectangular parallelepiped.
    • rpp shapes represent rectangular parallelepipeds (also known as cuboids and rectangular prisms), whose faces comprise three pairs of equal rectangles. If one pair of faces are squares, the volume is a square prism. If all of them are squares, the volume is a cube (geometrically, there cannot be just two pairs of square faces).
  • arb7 shapes represent hexahedra with four quadrilateral and two triangular faces. They have a total of eleven edges with seven unique vertices, one of which is shared by the two triangular faces. They can only be created by specifying the {X, Y, Z} coordinates of those vertices.
  • arb6 shapes represent triangular prisms and truncated tetrahedra, both of which have two triangular ends connected by three quadrilateral sides (its seems they should be called quintahedra but that term seems to be rarely used). Either has a total of nine edges with six unique vertices. In addition to simply specifying the {X, Y, Z} coordinates of their vertices, MGED provides an easier way to create one specific type of hexahedron:
    • raw (right angle wedge) shapes are triangular prisms whose ends are parallel to each other. Interestingly enough, they don't have to incorporate any right angles. If the ends are perpendicular to the connecting edges, the shape is a right triangular prism with rectangular sides. Presumably two of the rectangular sides of an actual right-angle wedge would also be perpendicular to each other. Such a shape could easily be created as a BRL-CAD raw primitive.
  • arb5 shapes represent quadrahedra, which are polyhedra with five faces—a quadrilateral base and the three triangular sides with a total of f. If such a volume has a rectangular base it is a rectangular pyramid, one with a square base is a square pyramid.
  • arb4 shapes represent tetrahedra, which are polyhedra with four triangular faces. If all four faces are equilateral triangles, the shape is a regular tetrahedron.

ARBN Records

An arbn record is specified by N sets of intersecting planes, each defined by four coefficients:

  • the {X, Y, Z} coefficients of the plane's normal vector pointing outward from the center of the arbn shape, and
  • the perpendicular distance of that plane from the origin.

As discussed in the Creating and editing arbn primitives article, BRL-CAD uses such primitives to represent polyhedra having any number of sides, edges and vertices.

Ellipsoids

ell

Ellipsoid

Handled by
make in form create
Arguments
vertex point, at the center
vectors A B C describing the radii of the ellipses; A points front, B points right, C points up.

Example:

in ell.s ell 0 0 0  0 -1 0  1 0 0  0 0 1

sph

Sphere, special case of the ellipsoid, with vectors A B and C all the same magnitude (radius).

Handled by
make in form(ell) create

Arguments:

vertex point, at the center
radius

ellg

Special case of ellipsoid

Handled by
in form(ell)
Arguments
two foci points, and axis length

ell1

Special case of ellipsoid

Handled by
in make form(ell) create
Arguments
vertex, vector A, radius of revolution

ehy

Elliptical hyperboloid

Handled by
make in form create
Arguments
vertex, perpendicular vectors Height and (A,r_1) major axis, (r_2) magnitude of vector B, (c) apex to asymptotes distance

epa

Elliptical paraboloid

Handled by
in make form create

Cones and Cylinders

tgc

Truncated general cone

Handled by
in make form create
Arguments
vertex, vectors H A B, magnitudes of vectors C D

rcc

Right circular cylinder, special case of tgc

Handled by
in make form(tgc) create
Arguments
vertex, height vector, radius

Example:

 in rcc1.s rcc 0 0 0  1 1 1  0.5

rec

Right elliptical cylinder, special case of tgc

Handled by
in make form(tgc) create
Arguments
vertex, height vector, radius

rhc

Right hyperbolic cylinder

Handled by
in make form create
Arguments
vertex, perpendicular vectors for Height and B, (r) rectangular half width, (c) apex to asymptote distance,

rpc

Right parabolic cylinder

Handled by
in make form create
Arguments
vertex, perpendicular vectors for Height and B, (r) rectangular half width

tec

Truncated elliptical cone, special case of tgc

Handled by
in make form(tgc) create
Arguments
Vertex, vectors Height, A, B

trc

Truncated right circular cone, special case of tgc

Handled by
in make form(tgc) create
Arguments
Vertex, Height vector, radius of base and top

derived from 2d

extrude

Extrusion of a 2-d sketch

Handled by
in make form(?) create
Arguments
vertex, perpendicular vectors Height A B, sketch, K

revolve

Revolution of a 2-d sketch

Handled by
in
Arguments
vertex, revolution axis, vector in start plane, angle, sketch

dsp

Handled by
in create
Arguments
data type (f|o), datasource, count of length and width, interpolation type, cut direction, cell size, unit elevation

See also DSP tutorial.

ebm

extruded bit map

Handled by
in form create
Arguments
filename, width and height in cells, extrusion distance,

See also EBM tutorial.

The extruded bitmap (also referred to as EBM) is a solid based on a greyscale bitmap. The bitmap is an array of unsigned char values, see bw(5), and is extruded by some distance. The EBM solid requires the dimensions of the bitmap file (height and width in bytes), an extrusion length, and a transformation matrix to position the EBM. Each byte in the bitmap file is treated as the base of a cell that is extruded by the specified extrusion length. If the value of the byte is non­zero, then that cell is considered solid.

hf

Height field

Handled by
none?
Status
depreciated, use dsp instead


Other solids

tor

Torus

Handled by
in make form create
Arguments
vertex, normal vector, radius of revolution, tube radius

eto

Elliptical torus

Handled by
in make form create
Arguments
vertex, normal vector, radius of revolution, vector C, (r_d) magnitude of semi-minor axis

part

Conical particle

Handled by
in make create
Arguments
vertex, height vector, radius at v, radius at h

The particle solid is a lozenge-shaped object defined by a vertex, a height vector and radii at both ends. The body of the particle is either a cylinder or a truncated cone, depending on the values of the radii. Each end of the particle is a hemisphere of the specified radius.

nmg

n-Manifold geometry solid (non-manifold geometry)

Handled by
make create

pipe

Hollow and solid pipes and wires

Handled by
in make create
Arguments
# points, for each point: location, inner and outer diameters, bend radius

ars

Arbitrary rectangular solid

Handled by
in make create

Solids of type 'ars' (Arbitrary Faceted Solids) are defined using "waterlines". The following figure consists of a start point, some number of intermediate polygons, and an ending point. Each of the intermediate polygons have the same number of vertices and the vertices are numbered 1 thru N. In addition to the intermediate polygons a line will be created that begins at the start point, goes through each polygon at its vertex numbered 1, and terminates at the end point. This is repeated for each polygon vertex 2 thru N. The start point, polygons, and end point are each a "waterline".

<need an image here to illustrate the concept>

the ars shape takes the following values as input:

  • The number of points per waterline (the number of vertices on each intermediate polygon)
  • The number of waterlines (the number of intermediate polygons plus 2)
  • X, Y, and Z for a starting point (the first waterline)
  • for each interior polygon (an intermediate waterline)
    • for each point on the polygon
      • X, Y, and Z for the point on the polygon
  • X, Y, and Z for an ending point (the last waterline)

For example, the command:

in x.1 ars 4 6 0 0 3 1 1 3 1 -1 3 -1 -1 3 -1 1 3 1 1 1 1 -1 1 -1 -1 1 -1 1 1 1 0 -1 0 -1 -1 -1 0 -1 0 1 -1 1 0 -3 0 -1 -3 -1 0 -3 0 1 -3 0 0 -3

Will produce a square bar with a tapered 1/8 turn twist in the middle. Of course, more waterlines in the twist and more points per waterline would make the twist smoother.

Example ARS



The parameters to the above ars command can be dissected as:

4 : number of points per waterline (i.e. intermediate polygons have 4 vertices)
6 : number of waterlines (four intermediate polygons plus the two endpoints)
0 0 3 - the center of the top end of the bar
1 1 3 1 -1 3 -1 -1 3 -1 1 3 : a 2x2 square in the xy plane at z offset 3
1 1 1 1 -1 1 -1 -1 1 -1 1 1 : a 2x2 square oriented the same as the first but at z offset 1
1 0 -1 0 -1 -1 -1 0 -1 0 1 -1 : a 2x2 square at a 45 degree rotation from the first squares at z offset -1
1 0 -3 0 -1 -3 -1 0 -3 0 1 -3 : a 2x2 square at a 45 degree rotation from the first squares at z offset -3
0 0 -3 : the center of the bottom end of the bar

metaball

Handled by
in make form(*) create
Arguments
render method, threshold, number of points, location and field strength for each point (and blobbiness/goo factor)


nurb

Non-uniform rational b-spline

Handled by
none?

spline

surface splines

Handled by
 ?

vol

volume / voxel

Handled by
in
Arguments
filename, xyz dimensions of file (in voxels), lower and upper threasholds, xyz dimensions of a cell

The vol solid is defined by a 3-dimensional array of unsigned char values. The solid requires a file of these values, the extent of the file (in bytes) in each dimension, the size of each cell, and high and low thresholds. Any value in the file that is between the thresholds (inclusive) represents a solid cell.

bot

Bag of triangles

Handled by
in make create (not edit!)
Arguments
number of verticies, number of triangles, mode (1=surface 2=solid 3=plate), triangle orientation mode (1=unoriented 2=counter-clockwise 3=clockwise), each vertex, vertex index of each triangle
See also
BoT

poly

polysolid

Handled by
none?
Status
depreciated, use bot instead

Other

Sketch

2d outline

Handled by
make form(sketch editor) create
See also
sketch

grip

Grip -- support for joints, non-geometric (does not show in rt)

Handled by
in make form create

Arguments:

Center
normal vector
magnitude

half

halfspace

Handled by
in make form create
Arguments
Normal, distance from origin

A half space is the portion of space on one side of a plane. It is represented by its boundary (the plane) and its outward-pointing normal vector.

binunif

Uniform-array binary object

Handled by
in create (not edit!)
Arguments
minor type (fdcsiLCSIL), data file, number of values