1. Introduction
2. 2D
Geometry
3. 3D Geometry
4. DXF
5. Display
6. Lists
7. Home
Copyright
(c) 1988-2009 Building Block Software, Inc. All rights reserved.
CAD/CAM
Developer's Kit/3D
Overview
========
The
Building Block Software CAD/CAM Developer's Kit / 3D (CCDK/3D) provides
functions
that enable your programs to create 3D
curves and points, and to
perform
computations with them. These functions
are collectively called
"3D
GEOMETRY".
The 3D
GEOMETRY collection is an extension of 2D GEOMETRY, the set of CCDK
routines
that perform 2D geometric
operations. CCDK/3D adds "pure
3D"
operations
such as projecting a circle onto a
plane to create an ellipse,
and it enables a 3d mode called "2D-on-a-3D
plane".
Geometry
in the "2D-on-a-3D plane" mode is defined in a 2D "local coordinate
system"
positioned in 3D space, and remains in 2D format. When any
information
on this plane is required in 3D format, such as for display, it
is
converted to 3D using the transformation
associated with the local
coordinate
system. Similarly, information in 3D can be projected into this
2D
coordinate system.
3D
curve parameters are handled identically to those in 2D, so a review of
the
Curve Parameters section of the 2D GEOMETRY
Reference is recommended before
reading
this reference.
Both of
the 3D modes provided by the 3D GEOMETRY functions are useful for
applications
such as:
*
architectural design
* sheet
metal bending
* NC
programming for milling and wire EDM
*
surface design
Fundamental
Concepts
====================
Introduction
------------
This
section describes 3D objects and operations without getting into any
programming
details. The purpose of this section is
to provide a basis for
the
sections of this reference that present
programming information.
3D
Objects
----------
The 3D
object types supported by 3D GEOMETRY are:
*
points and vectors
*
curves
*
bounding boxes
*
transform
A point
is a set of cartesian coordinates. A
vector is a set of cartesian
coordinates
that is the difference between two
points.
A curve
is a general object that can represent
any of these specific types:
* line
* arc
*
ellipse
*
polycurve
*
B-spline
A line
is a linear segment.
An arc
is a part or all of a full circle.
An
ellipse is an elliptical segment.
A
polycurve is an end-to-end chain of line and arc segments.
A
Non-Uniform Rational B-spline (NURB-spline) is a general type of B-spline.
A
bounding box is a 3D rectangular prism, usually used to record the extents
of a 3D
object. This box is aligned with
the coordinate axes.
Bounding
boxes are useful for determining the approximate locations and
sizes
of 3D objects. This information can be
applied to "cull" objects
from
a set
to increase performance. For example,
drawing performance is increased
for the
"zoom" operation if objects whose
bounding boxes do not appear in
the
view are skipped.
A
transform is a matrix used to transform objects from one coordinate system
into
another.
Curve
Properties
----------------
CCDK/3D
takes advantage of a set of curve properties to enable all curves to
be
treated as one type.
These
curve properties summarized by the following
statements:
* Every
curve has a start point, an end point and an
"orientation"; if it is
closed, the start point and the end
point are the same; the orientation is
the direction one follows along the curve to travel from its start point
to its end point.
* For
each point on a curve, there is a corresponding real number called a
parameter value; in mathematical terms,
there is a "one-to-one
mapping"
between points on a curve and a
continuous range of real numbers.
* At
each point on a curve, one may evaluate a tangent vector, and other
mathematical properties.
*
Curves may be rotated, scaled, translated, mirrored, intersected and
trimmed.
Treating
all curve types as one type with these properties eliminates the
need to
have a separate function for each curve type
for each operation.
Instead,
there is only one function for each
operation.
3D
Geometric Operations
-----------------------
This
section presents the 3D operations provided by CCDK/3D functions.
3D
operations consist of four categories:
* point
and vector
* curve
*
bounding box
*
transform
Point
and vector operations are divided into
four groups:
*
construction
*
evaluation
*
addition and multiplication
*
conversion between 2D and 3D
Construction
functions create points and vectors, and set
coordinate values.
They also create copies of points and vectors, and build points and vectors
from
other points and vectors. They also perform transformations such as
rotation,
scaling, mirroring and projection.
Evaluation
functions compute properties of points and
vectors, such as
distances,
lengths, and angles.
Addition
and multiplication functions perform standard
vector operations,
including
weighted sums, dot and cross products.
Conversion
operations transform points and vectors between 3D space and 2D
local
coordinate systems.
Curve
functions are divided into:
*
construction
*
copying
*
modification
*
evaluation
* 2D
<-> 3D conversion
Construction
operations create geometry from input information. Creating an
arc
passing through three points is one example of a construction operation.
Copying
operations create copies of curves, optionally with alterations such
as
transformations or trimming.
Modification
operations, which change existing geometry, include:
*
trimming
*
breaking
*
rotation
* scaling
*
mirroring
*
translation
Evaluation
operations compute information about geometry such as: end point
coordinates,
tangent vectors, and lengths.
2D<->3D
conversion operations are the link between 3D space and the 2D local
coordinate
systems positioned in 3D space.
These operations convert 3D
curves
lying on the plane of a local
coordinate system into 2D equivalents
expressed
in coordinates relative to the origin,
x and y axes of the local
coordinate
system. They also bring 2D curves
defined in a local coordinate
system
back into 3D format.
Intersection
of 3D curves is performed by using 2D
intersection routines.
If the
3D curves to be intersected are planar
and are in the same plane,
they
can be converted into 2D in a local
coordinate system on the plane, and
intersected
as 2D curves. The curve parameters of
the intersection points
on the
2D curves also correspond to the
intersection points on the 3D
curves.
If the
3D curves are not planar, or in the same plane, they can be projected
onto a
single plane and intersected as described above. This technique can
be used
to find points where 3D curves appear to
intersect when viewed along
the
normal of the plane onto which they are
projected for intersection.
These
intersection points are called
"apparent" intersections.
Bounding
box operations are divided into:
*
construction
*
evaluation
Construction
operations create and build bounding boxes.
Evaluation
consists of a test that determines if two bounding boxes overlap.
Transform
operations are divided into:
*
construction
*
evaluation
Construction
operations create and combine transforms. Transforms are
constructed
from the axes of coordinate systems.
Evaluation
consists of applying transforms to points and
vectors in one
coordinate
system to obtain their coordinates in
another coordinate system.
Types
=====
Introduction
------------
This
section presents programming information for creating and using the
objects
in defined by CCDK/3D. Use this section
of the manual to locate the
name of
object types and the access macros that access
the attributes of
these
types.
Type
Overview
-------------
The
types provided by CCDK/3D include:
* point
or vector
*
bounding box
* curve
*
transform
A point
or vector represents a position or a direction in 3D space.
A
bounding box is a rectangular prism, used to record the volume spanned by
a 3D
object.
A curve
represents curve geometry, including lines, arcs, circles,
polycurves
and NURB-splines. Some curves, such
as ellipses, parabolas, and
hyperbolas,
can be represented precisely by
NURB-splines. Other curves,
such as
sine and cosine curves can be
approximated to a specified degree of
accuracy.
A
transform is a matrix used to transform objects from one coordinate system
to
another.
The
sections below provide information about the type definitions provided
by
CCDK/3D for representing and using these objects.
Point
------
One
object type represents both points and vectors. Although points and
vectors
are conceptually different, they may be represented by the same type
and
processed by the same routines.
______________________________________________________________________________
|
Type |
Meaning |
|----------------------------------------------------------------------------|
|
PT3 | a
3D point or vector |
|
PT3 | a
pointer to a 3D point or vector |
------------------------------------------------------------------------------
Declaring
a variable of type PT3 allocates uninitialized space for three
coordinate
values. The coordinates values must be
set using access macros,
or with
the function c3v_set.
These
types are defined in the header file c3defs.h.
The
following macros access the coordinates of points and components of
vectors:
______________________________________________________________________________
|
Macro |
Meaning |
|----------------------------------------------------------------------------|
|
PT3_X(P) | a REAL which is the x
coordinate |
| | of 3D
point P |
|
PT3_Y(P) | a
REAL which is the y coordinate |
| | of 3D point P |
|
PT3_Z(P) | a
REAL which is the z coordinate |
| | of 3D
point P |
------------------------------------------------------------------------------
These
macros are defined in the header file c3defs.h.
Bounding
Box
------------
Bounding
boxes are represented by these types:
______________________________________________________________________________
|
Type | Meaning |
|----------------------------------------------------------------------------|
|
C3_BOX_S | a
3D bounding box structure |
|
C3_BOX | a 3D bounding box |
------------------------------------------------------------------------------
These
types are defined in the header file c3defs.h.
The
term "bounding box" means an object of type C3_BOX. This object is a
pointer
to a bounding box structure.
When a
bounding box is used as working space or for output, it must refer to
a
bounding box structure that has been declared as an automatic variable, or
has
been allocated.
When
declaring automatic storage, it is often convenient to declare both a
structure
and a pointer to the structure to avoid repetitive evaluation of
the
structure address:
C3_BOX_S
box_s;
C3_BOX
box = &box_s;
Alternatively,
memory for a bounding box may be allocated with c3a_box:
C3_BOX
box = c3a_box ( NULL, NULL );
When an
allocated bounding box is no longer needed, it must be freed with
c3a_free_box.
The
following macros access bounding box information:
______________________________________________________________________________
|
Macro |
Meaning |
|----------------------------------------------------------------------------|
|
C3_MIN_PT(B) | a
PT3 which specifies the bottom |
| | left
back corner of bounding box |
| | B |
|
C3_MAX_PT(B) | a
PT3 which specifies the top |
| | right
front corner of bounding |
| | box
B |
|
C3_MIN_X(B) | a
REAL which specifies the x |
| | coordinate of the bottom left
|
| | back
corner of bounding box B |
|
C3_MIN_Y(B) | a
REAL which specifies the y |
| | coordinate of the bottom left
|
| | back
corner of bounding box B |
|
C3_MIN_Z(B) | a
REAL which specifies the z |
| | coordinate
of the bottom left |
| | back
corner of bounding box B |
|
C3_MAX_X(B) | a
REAL which specifies the x |
| |
coordinate of the top right front |
| | corner
of bounding box B |
|
C3_MAX_Y(B) | a
REAL which specifies the y |
| |
coordinate of the top right front |
| | corner
of bounding box B |
|
C3_MAX_Z(B) | a
REAL which specifies the z |
| |
coordinate of the top right front |
| | corner of bounding box B |
------------------------------------------------------------------------------
These
macros are defined in the header file c3defs.h.
Curve
-----
The
following object type defines a 3D curve:
______________________________________________________________________________
|
Type |
Meaning |
|----------------------------------------------------------------------------|
| C3_CURVE | a 3D curve |
------------------------------------------------------------------------------
An
object of type C3_CURVE can be used to represent a line, an arc, a
circle,
an ellipse, a polycurve or a B-spline.
"Create" functions are
provided
to create each of these geometry types.
C3_CURVE
is defined in the header file c3defs.h.
The
following macros access curve parameters:
______________________________________________________________________________
|
Type |
Meaning |
|----------------------------------------------------------------------------|
|
C3_CURVE_PARM0(C) | a
PARM corresponding to the start |
| | point
of curve C |
|
C3_CURVE_PARM1(C) | a
PARM corresponding to the end |
| | point
of curve C |
| C3_CURVE_T0(C) | a REAL specifying the
curve |
| |
parameter value of the start |
| | point
of curve C |
|
C3_CURVE_T1(C) | a REAL specifying the
curve |
| |
parameter value of the end point |
| | of
curve C |
------------------------------------------------------------------------------
The
following macros access curve bounding boxes:
______________________________________________________________________________
|
Macro |
Meaning |
|----------------------------------------------------------------------------|
|
C3_CURVE_BOX(C) | a
C3_BOX which is the bounding box |
| | of
curve C |
|
C3_CURVE_X_MIN(C) | a
REAL which is the x coordinate |
| | of the
lower left back corner of |
| | the
bounding box of curve C |
|
C3_CURVE_X_MAX(C) | a REAL which is the x
coordinate |
| | of the
upper right front corner |
| | of the
bounding box of curve C |
|
C3_CURVE_Y_MIN(C) | a
REAL which is the y coordinate |
| | of the
lower left back corner of |
| | the
bounding box of curve C |
|
C3_CURVE_Y_MAX(C) | a
REAL which is the y coordinate |
| | of the
lower left back corner of |
| | the
bounding box of curve C |
|
C3_CURVE_Z_MIN(C) | a
REAL which is the z coordinate |
| | of the
lower left back corner of |
| | the
bounding box of curve C |
|
C3_CURVE_Z_MAX(C) | a
REAL which is the z coordinate |
| | of the lower left back corner
of |
| | the
bounding box of curve C |
------------------------------------------------------------------------------
The
following macros report curve type:
______________________________________________________________________________
|
Macro |
Meaning |
|----------------------------------------------------------------------------|
|
C3_CURVE_IS_LINE(C) |
TRUE if curve C is a 3D line; |
| | FALSE
otherwise |
|
C3_CURVE_IS_ARC(C) |
TRUE if curve C is a 3D arc or |
| | circle; FALSE otherwise |
|
C3_CURVE_IS_PCURVE(C) |
TRUE if curve C is a 3D polycurve; |
| | FALSE
otherwise |
------------------------------------------------------------------------------
These
macros are defined in the header file c3defs.h.
Also,
if the symbol SPLINE is defined, the following macros are defined.
______________________________________________________________________________
|
Type |
Meaning |
|----------------------------------------------------------------------------|
|
C3_CURVE_IS_ELLIPSE(C) |
TRUE if curve C is a 3D ellipse; |
| | FALSE otherwise |
------------------------------------------------------------------------------
These
macros are defined in the header file c3defs.h.
Transform
---------
3D
transforms are represented by the type:
______________________________________________________________________________
|
Type |
Meaning |
|----------------------------------------------------------------------------|
|
C3_TRANSFORM | a
3D transform |
------------------------------------------------------------------------------
This
type is defined in the header file c3defs.h.
When a
transform is used as working space or for output, it must be declared
as an
automatic variable, or it must be allocated
dynamically.
Declaring
an automatic variable of type C3_TRANSFORM allocates space for the
transform
matrix.
To
allocate dynamic memory for a transform, use c3t_create:
C3_TRANSFORM
*t = c3t_create();
When an
allocated transform is no longer needed, it must be freed with
c3t_free.
Functions
and Macros By Category
================================
Introduction
------------
This
section presents CCDK/3D functions grouped according to the operations
that
they perform.
Category
Overview
-----------------
The
general categories that all CCDK/3D functions fall into are:
*
point/vector functions
* curve
functions
* bounding
box functions
*
transform functions
Functions
that perform point and vector operations are
divided into the
following
groups:
*
construction
*
evaluation
*
addition and multiplication
*
2D<->3D conversion
Construction
functions create points and vectors.
Evaluation functions
compute
point and vector properties such as
distances and angles. Addition
and
multiplication functions provide
standard point and vector computations.
2D<-> 3D functions provide
transformations between 3D space and 2D
local
coordinate
systems positioned in 3D space.
Functions
that perform curve operations are divided
into the following
groups:
*
construction
*
copying
*
modification
*
evaluation
* 2D
<-> 3D conversion
Construction
functions create 3D curves. Copying
functions create copies of
curves,
with optional alterations. Modification
functions change existing
curves. Evaluation functions compute curve
properties such as coordinates
and
tangent vectors. 2D<->3D functions provide transformations between 3D
space
and 2D local coordinate systems
positioned in 3D space.
Functions
that perform bounding box operations are
divided into the
following
groups:
*
construction
*
evaluation
Construction
functions create and modify bounding boxes.
Evaluation
is testing if bounding boxes overlap or interfere.
Functions
that perform transform operations are
divided into the following
groups:
*
construction
*
evaluation
Construction
functions create and combine transforms. Evaluation apply
transforms
to points and vectors.
Function
Prefixes
-----------------
All
CCDK/3D functions begin with a three character
prefix that indicates the
general
purpose of the function. The table below lists the prefixes used in
CCDK/3D
and their meaning.
______________________________________________________________________________
|
Prefix |
Meaning |
|----------------------------------------------------------------------------|
|
c3v |
point- and vector-related |
|
c3d |
curve creation and copying |
|
c3c |
curve modification and evaluation |
|
c3a |
bounding box |
|
c3t |
transform |
------------------------------------------------------------------------------
Point/Vector
Construction
-------------------------
CCDK/3D
provides a variety of point and vector construction functions.
The
following CCDK/3D functions create new points and vectors:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3d_point |
to allocate a point |
|
c3v_set |
to set the coordinates of a point |
|
c3v_set_zero |
to set the coordinates of a point |
| | to
(0,0,0) |
|
c3d_free_point |
to free a point |
------------------------------------------------------------------------------
The
following CCDK/3D functions build points and
vectors from other vectors:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_copy | to copy a point or a
vector |
|
c3v_negate |
to construct a vector which has |
| | the
reverse direction of a given |
| | vector |
|
c3v_mid_pt |
to construct the midpoint between |
| | two
vectors |
|
c3v_unit_normal |
to construct a vector of unit |
| | length
perpendicular to two given |
| |
vectors |
|
c3v_project_line |
to project a point onto a line |
| |
segment defined by two points |
|
c3v_basis
| to construct two
perpendicular |
| | unit
vectors which are both |
| | perpendicular to a given
vector; |
| | used
for creating the x and y |
| | axes
of a local coordinate system |
------------------------------------------------------------------------------
The
following functions normalize vectors:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_normalize |
to divide each component of a |
| | vector
by its length to produce a |
| | vector of unit length |
|
c3v_normalize_l1 |
to divide the components of a |
| | vector
by its "Manhattan
length"; |
| | produces a vector whose length
is |
| | close
to one |
------------------------------------------------------------------------------
The
following functions rotate and scale points and vectors:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_rotate_pt |
to rotate a point about an axis |
|
c3v_rotate_pt_cs |
to rotate a point about an axis |
| | given
the cosine and sine of the |
| | rotation angle |
|
c3v_rotate_vec |
to rotate a vector about an axis |
|
c3v_rotate_vec_cs |
to rotate a vector about an axis |
| | given the cosine and
sine of the |
| |
rotation angle |
|
c3v_scale |
to multiply a vector by a scalar |
|
c3v_mirror_pt | to mirror a point about a plane |
| |
defined by a normal vector and a |
| |
distance from the origin |
|
c3v_mirror_vec |
to mirror a vector about a plane |
| |
defined by a normal vector and a |
| |
distance from the origin |
------------------------------------------------------------------------------
The
following functions project points and vectors onto planes:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_project_pt_normal |
to project a point orthogonally |
| | onto a
plane |
|
c3v_project_pt_oblique | to project a point onto a plane |
| | along
a specified direction |
|
c3v_project_vec_normal |
to project a vector orthogonally |
| | onto a
plane |
|
c3v_project_vec_oblique |
to project a vector onto a plane |
| | along
a specified direction |
|
c3v_plane_3pts |
to construct a plane from three |
| |
points |
|
c3v_pt_on_plane |
to determine if a point is on a |
| |
plane |
|
c3v_vec_on_plane |
to determine if a vector is on a |
| |
plane |
------------------------------------------------------------------------------
When
using point/vector construction functions, include the header file
c3ddefs.h
or c3vdefs.h, depending on the prefix.
Point/Vector
Evaluation
-----------------------
Once
points and vectors are constructed, CCDK/3D functions can be used to
compute
their properties.
The
following functions compute distances and lengths:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_dist |
to compute the distance between |
| | two
points |
|
c3v_dist_squared |
to compute the square of the |
| |
distance between two points |
|
c3v_distl1 |
to compute the "Manhattan"
|
| |
distance (the sum of the absolute |
| | values
of the components) between |
| | two
points |
|
c3v_norm |
to compute the length of a vector |
|
c3v_norm_squared |
to compute the square of the |
| | length
of a vector |
|
c3v_norml1 |
to compute the "Manhattan" length
|
| | of a vector |
|
c3v_ident_pts |
to determine if two points |
| |
coincide within the absolute |
| | tolerance |
|
c3v_is_small |
to determine if the absolute |
| | values
of all of the coordinates |
| | are
less that the absolute |
| |
tolerance |
------------------------------------------------------------------------------
The
following functions compute angles related to
points and vectors:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_vecs_angle |
to compute the angle between two |
| |
vectors |
|
c3v_vecs_cos |
to compute the cosine of the angle |
| | between two vectors |
|
c3v_vecs_sin |
to compute the sine of the angle |
| |
between two vectors |
|
c3v_vecs_parallel | to determine if the angle
between |
| | two
vectors is less than the |
| |
relative tolerance |
|
c3v_spherical |
to compute the spherical |
| |
coordinates of a 3D point |
|
c3v_set_spherical |
to set the direction of a 3D |
| | vector
to a direction specified |
| | by
spherical coordinates |
------------------------------------------------------------------------------
When
using point/vector evaluation functions, include the header file
c3vdefs.h.
Point/Vector
Addition and Multiplication
----------------------------------------
CCDK/3D
provides two sets of functions for standard vector computations.
The
following functions perform vector addition and subtraction:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_add | to add to vectors |
|
c3v_addc |
to compute the sum of a vector and |
| | the
weighted sum of two other |
| | vectors |
|
c3v_addt |
to compute the sum of a vector and |
| | a
multiple of another vector |
|
c3v_addu |
to compute the convex combination |
| | of two
vectors |
|
c3v_addw |
to compute the weighted sum of two |
| |
vectors |
|
c3v_sub |
to subtract two vectors |
|
AD |
tion Use |
------------------------------------------------------------------------------
When
using vector computation functions, include the header file c3vdefs.h.
2D<->3D
Point/Vector Conversion
-------------------------------
The
following functions convert points and vectors
between 3D and 2D
formats:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3v_conv_pt_3d2d |
to convert a 3D point into a 2D |
| | point
in a local coordinate |
| |
system |
|
c3v_conv_pt_2d3d |
to convert a 2D point in a local |
| |
coordinate system into a 3D point |
| | |
|
c3v_conv_vec_3d2d |
to convert a 3D vector into a 2D |
| | vector
in a local coordinate |
| |
system |
|
c3v_conv_vec_2d3d |
to convert a 2D vector in a local |
| | coordinate system into a 3D |
| |
vector |
|
c3v_coord_sys
| to construct a local
coordinate |
| | system on a plane |
------------------------------------------------------------------------------
When
using point/vector conversion functions, include the header file
c3vdefs.h.
Curve
Construction
------------------
CCDK/3D
provides two groups of curve construction functions. One set
creates
single-segment curves, and the other creates polycurves, which are
multi-segment
chains of lines and arcs.
The
following functions create single-segment curves:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3d_line | to construct a line
defined by two |
| |
points |
|
c3d_line_dir |
to construct a line defined by a |
| | point and a direction vector
|
|
c3d_ray |
to construct a line defined by a |
| | point
and the spherical angles of |
| | its
direction |
|
c3d_arc_3pts |
to create an arc passing through |
| | three
points |
|
c3d_arc_2pts_tan |
to construct an arc starting at |
| | one
point with a specified |
| |
tangent, and ending at another |
| |
point |
| c3d_arc_2pts_ctr | to construct an arc
with a given |
| |
center, starting at one point and |
| | ending
at another |
|
c3d_circle | to construct a circle
defined by a |
| | center
point, normal and a radius |
------------------------------------------------------------------------------
@TABLEHEAD
= The following functions construct splines.
They are available
only
when the symbol SPLINE is defined:
parameterization
The
following functions create polycurves:
______________________________________________________________________________
|
Function | Use |
|----------------------------------------------------------------------------|
|
c3d_pcurve_init |
to start a polycurve |
|
c3d_pcurve_through |
to create a polygonal polycurve |
| |
through a set of points |
|
c3d_pcurve_add_arc_2pts |
to add an arc to the end of a |
| |
polycurve starting at the end |
| | point,
and passing through two |
| | given
points |
|
c3d_pcurve_add_arc_tan |
to add an arc to the end of a |
| |
polycurve tangent to the endpoint |
| | and
ending at a specified point |
|
c3d_pcurve_add_arc_ctr_pt |
to add an arc to the end of a |
| | polycurve starting at the
end |
| | point,
having a specified center, |
| | and
ending at a specified point |
|
c3d_pcurve_add_line | to add a line segment to the
end |
| | of a
polyline |
|
c3d_pcurve_add_line_tan |
to add a line to the end of a |
| |
polycurve tangent to the end |
| | point,
and ending at a specified |
| |
point |
|
c3d_pcurve_remove_last |
to remove the last segment from a |
| |
polycurve |
|
c3d_pcurve_close |
to add a segment to close a |
| |
polycurve |
------------------------------------------------------------------------------
The
function c3d_pcurve_segment creates a C3_CURVE object from a specified
segment
of a 3D polycurve.
The
function c3d_curve_to_spline converts all curve types to splines.
The
function c3d_free_curve frees curves.
When
using curve construction functions, include the header file c3ddefs.h.
Curve
Copying
-------------
CCDK/3D
provides a number of curve copying functions.
Many of these
functions
not only copy a curve, but also apply some other operation such as
transformation
or trimming.
The
function c3d_copy creates an identical copy of a curve.
The
following functions make transformed copies of 3D curves:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3d_rotate |
to create a curve which is the |
| |
rotation of a curve |
|
c3d_rotate_cs |
to create a curve which is the |
| |
rotation of a curve; the rotation |
| | angle
is specified with its cosine |
| | and
sine; this routine makes |
| |
rotating batches of geometry more |
| |
efficient |
|
c3d_scale |
to create a curve which is the |
| | scale
of a curve |
|
c3d_translate |
to create a curve which is the |
| |
translation of a curve |
|
c3d_mirror |
to create a curve which is the |
| | mirror image of a curve about a
|
| |
plane |
|
c3d_transform |
to create a copy of a curve, and |
| | to
transform the copy |
------------------------------------------------------------------------------
The
following functions make trimmed copies of 3D
curves:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3d_trim0 |
to create a curve by copying a |
| | curve and trimming away the |
| |
"start portion" of the copy; the
|
| |
portion of the copy from the |
| | trimming point to the end
point is |
| |
retained ; the trimming point is |
| |
specified with a parameter record |
|
c3d_trim1 |
to create a curve by copying a |
| | curve
and trimming away the "end |
| |
portion" of the copy; the portion
|
| | of the
copy from the start point |
| | to the
trimming point is retained; |
| | the
trimming point is specified |
| | with a
parameter record |
|
c3d_trim |
to create a curve by copying a |
| | curve
and trimming away both ends |
| | of the
copy; the portion of the |
| | copy between the trimming points
|
| | is
retained; the trimming points |
| | are
specified with parameter |
| | records |
|
c3d_trim_t0 |
to create a curve by copying a |
| | curve
and trimming away the |
| |
"start portion" of the copy; the
|
| |
portion of the copy from the |
| |
trimming point to the end point |
| | is
retained; the trimming point is |
| |
specified with a parameter value |
|
c3d_trim_t1 |
to create a curve by copying a |
| | curve
and trimming away the "end |
| |
portion" of the copy; the portion
|
| | of the
copy from the start point |
| | to the
trimming point is retained; |
| | the trimming point is
specified |
| | with a
parameter value |
|
c3d_trim_t |
to create a curve by copying a |
| | curve and trimming away
both ends |
| | of the
copy; the portion of the |
| | copy
between the trimming points |
| | is
retained; the trimming points |
| | are
specified with parameter |
| |
values |
------------------------------------------------------------------------------
The
following functions create copies of 3D curves
projected on specified
planes:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3d_project_normal |
to create a curve which is the |
| |
orthogonal projection of a |
| |
specified curve onto a specified |
| |
plane |
|
c3d_project_oblique |
to create a curve which is the |
| | projection of a specified curve
|
| | onto a
specified plane along a |
| |
specified direction |
|
ng |
@SECTION = Curve Modification
|
------------------------------------------------------------------------------
The
following functions modify 3D curves by rotating, scaling, translation
and
mirroring them:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_rotate |
to rotate a curve about an axis |
|
c3c_rotate_cs |
to rotate a curve about an axis |
| | given
the cosine and sine of the |
| |
rotation angle |
|
c3c_scale |
to scale a curve |
|
c3c_translate |
to translate a curve |
|
c3c_mirror |
to mirror a curve about a plane |
|
c3c_transform |
to transform a curve |
------------------------------------------------------------------------------
The
following functions project 3D curves onto planes:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_project_normal |
to project a curve orthogonally |
| | onto a
specified plane |
|
c3c_project_oblique |
to project a curve onto a |
| |
specified plane along a specified |
| |
direction |
------------------------------------------------------------------------------
The
following functions trim 3D curves:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_trim0 |
to trim away the "start portion"
|
| | of a
curve; the portion of the |
| | curve
from the trimming point to |
| | the
end point is retained; the |
| |
trimming point is specified with a |
| |
parameter record |
|
c3c_trim1 |
to trim away the "end portion" of
|
| | a
curve; the portion of the curve |
| | from
the start point to the |
| |
trimming point is retained; the |
| | trimming point is specified with a |
| |
parameter record |
|
c3c_trim |
to trim away both ends of a curve; |
| | the portion of the curve between
|
| | the
trimming points is retained; |
| | the
trimming points are specified |
| | with parameter
records |
|
c3c_trim_t0 |
to trim away the "start portion"
|
| | of a
curve; the portion of the |
| | curve
from the trimming point to |
| | the
end point is retained; the |
| |
trimming point is specified with a |
| |
parameter value |
|
c3c_trim_t1 |
to trim away the "end portion" of
|
| | a
curve; the portion of the curve |
| | from
the start point to the |
| | trimming point is retained; the |
| |
trimming point is specified with a |
| |
parameter value |
|
c3c_trim_t | to trim away both ends of a
curve; |
| | the
portion of the curve between |
| | the
trimming points is retained; |
| | the trimming
points are specified |
| | with
parameter values |
------------------------------------------------------------------------------
When
using curve modification functions, include the header file c3cdefs.h.
Curve
Evaluation
----------------
The
following functions compute coordinates and
tangent vectors at the start
and end
points of 3D curves:
______________________________________________________________________________
| Function | Use |
|----------------------------------------------------------------------------|
|
c3c_ept0 |
to compute the coordinates of the |
| | start point of a curve |
|
c3c_ept1 |
to compute the coordinates of the |
| | end
point of a curve |
|
c3c_ept_tan0 | to evaluate the coordinates and |
| | the
tangent vector at the start |
| | point
of a curve |
|
c3c_ept_tan1 |
to evaluate the coordinates and |
| | the
tangent vector at the end |
| | point
of a curve |
|
c3c_etan0 |
to evaluate the tangent vector at |
| | the
start point of a curve |
|
c3c_etan1 |
to evaluate the tangent vector at |
| | the
end point of a curve |
| c3c_closed | to determine if a
curve is closed |
------------------------------------------------------------------------------
The
following functions compute coordinates and tangent vectors at any
specified
point on a 3D curve:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_eval_pt |
to compute or to evaluate the |
| |
coordinates of a point on a curve |
| |
specified by a curve parameter |
| | record |
|
c3c_eval_pt_tan |
to evaluate the coordinates and |
| | the
tangent vector of a curve at |
| | a
location specified by a curve |
| |
parameter record |
|
c3c_eval_tan |
to evaluate a tangent vector of a |
| | curve
at a location specified by |
| | a
curve parameter record |
|
c3c_info_curve |
to print information about a curve |
------------------------------------------------------------------------------
The
function c3c_length computes the length of a 3D curve.
The
function c3c_project projects a points onto a 3D curve. A
related
function,
c3c_select, determines if a point is within
a specified distance
from a
3D curve.
The
following functions compute information about curves which are arcs,
circles
and ellipses.
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_get_arc_data |
to obtain the center, radius, |
| | normal
and sweep of a 3D arc |
|
c3c_get_arc_radius | to obtain the radius of an
arc |
|
c3c_get_arc_center |
to obtain the center point of an |
| |
arc |
|
c3c_get_arc_normal | to
obtain the start angle of an |
| | arc;
the result is in radians |
|
c3c_get_arc_sweep |
to obtain the sweep of an arc; the |
| | result
is in radians |
|
c3c_arc_angle |
to compute the arc angle |
| |
corresponding to a specified |
| | curve
parameter |
|
c3c_arc_parm |
to compute the arc curve parameter |
| |
corresponding to a specified |
| |
angle |
|
c3c_get_ellipse_data |
to obtain the center, major and |
| | minor
axes of an ellipse; |
| |
available only if SPLINE is |
| | defined |
|
c3c_get_pcurve_data |
to obtain information about a |
| |
specified segment of a polycurve |
------------------------------------------------------------------------------
Include
c3cdefs.h when using arc, ellipse and polycurve information
routines.
The
following functions create linear interpolations, or "polygonal
approximations",
of 3D curves. The precision of approximation is controlled
by a
specified maximum chordal deviation
from the curve being interpolated.
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_approx |
to compute a linear approximation |
| | of a
curve |
|
c3c_approx_init |
to initialize a linear |
| |
approximation of a curve |
------------------------------------------------------------------------------
When
using curve evaluation functions, include the header file c3cdefs.h.
2D
<-> 3D Curve Conversion
--------------------------
The
following functions convert curves from 3D format to 2D, and vice versa.
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3c_on_plane |
to determine if a 3D curve is on a |
| |
plane |
|
c3c_plane |
to determine the plane on which a |
| | 3D
curve lies |
|
c3c_curves_plane |
to determine the plane on which a |
| | set of
3D curves lie |
|
c3d_convert_3d2d |
to convert a 3D curve into a 2D |
| | curve in a specified local |
| |
coordinate system |
|
c3d_convert_2d3d |
to convert a 2D curve in a |
| |
specified local coordinate system |
| | into a
3D curve |
------------------------------------------------------------------------------
When
using curve conversion functions, include the header file c3cdefs.h or
c3ddefs.h,
depending on the prefix.
Bounding
Box Construction and Testing
-------------------------------------
The
following functions create and modify bounding
boxes:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3a_box |
to allocate a bounding box |
|
c3a_box_init_pt |
to initialize both corners of a |
| |
bounding box to a point |
|
c3a_box_append_pt |
to expand a bounding box to |
| | contain a point |
|
c3a_box_append |
to expand a bounding box to |
| |
contain another bounding box |
|
c3a_box_union | to create a bounding box
that |
| |
contains two bounding boxes |
|
c3a_free_box |
to free a bounding box |
|
c3a_box_copy | to
copy a bounding box |
------------------------------------------------------------------------------
The
following function determine if bounding boxes
overlap:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3a_box_overlap |
to determine if two bounding boxes |
| | overlap |
|
c3a_box_w_overlap |
to determine if two bounding boxes |
| |
overlap, or are within a |
| | specified distance |
------------------------------------------------------------------------------
When
using bounding box functions, include the header file c3adefs.h.
Transform
Construction and Evaluation
-------------------------------------
The
following functions create and modify 3D transforms:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3t_create |
to create an identity transform |
|
c3t_mirror |
to construct a 3D transform for |
| | mirroring about a plane |
|
c3t_rotate |
to construct a 3D transform for |
| |
rotating about an axis by a given |
| | angle |
|
c3t_rotate_cs |
to construct a 3D transform for |
| |
rotating about an axis, where the |
| | rotation
axis is specified with |
| | its
cosine and sine |
|
c3t_scale |
to construct a 3D transform for |
| |
scaling about a point |
|
c3t_translate |
to construct a 3D transform for |
| |
translating |
|
c3t_inverse |
to compute the inverse of a 3D |
| |
transform |
|
c3t_orthogonal |
to determine if a transform is |
| |
orthogonal |
|
c3t_lcs | to compute a transform for |
| |
transforming objects from the |
| | global
coordinate system to a |
| | local coordinate system |
|
c3t_mult |
to multiply two transforms |
|
c3t_free |
to free a transform |
------------------------------------------------------------------------------
The
following functions transform points and vectors:
______________________________________________________________________________
|
Function |
Use |
|----------------------------------------------------------------------------|
|
c3t_eval_pt |
to transform a point |
|
c3t_eval_vec |
to transform a vector |
------------------------------------------------------------------------------
When
using transform functions, include the header file c3tdefs.h.
Alphabetized
Reference
======================
@NEWPAGE
=
***>>
c3a_box <<***
******
Summary ******
#include
<c3adefs.h>
C3_BOX
c3a_box ( min_pt, max_pt );
******
Description ******
This
function creates a bounding box initialized to the rectangular prism
defined
by two given points.
******
Input ******
------------------------------------------------------------------------------
|
PT3 | min_pt,
max_pt | the lower left back
and |
| | | upper right front
corner |
| | | points of the bounding box; |
| | | if either is NULL,
the |
| | | bounding box is
created, |
| | | but not initialized |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is a pointer to a bounding box.
If memory could not be
allocated,
NULL is returned.
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1;
C3_BOX box;
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box = c3a_box ( p0, p1 );
c3a_free_box ( box );
}
This
program creates a bounding box with corners (2,3,1) and (5,6,4).
***>>
c3a_box_append <<***
******
Summary ******
#include
<c3adefs.h>
void
c3a_box_append ( box, append_box );
******
Description ******
This
routine expands a bounding box to include another bounding box.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box | the box to expand |
------------------------------------------------------------------------------
|
C3_BOX | append_box | the box fitted into the |
| | | expanded box |
------------------------------------------------------------------------------
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1;
C3_BOX box0, box1;
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box0 = c3a_box ( p0, p1 );
c3v_set ( 3.0, 4.0, 5.0, p0 );
c3v_set ( 7.0, 8.0, 6.0, p1 );
box1 = c3a_box ( p0, p1 );
c3a_box_append ( box0, box1 );
c3a_free_box ( box0 );
c3a_free_box ( box1 );
}
This
program creates two bounding boxes and then expands the first to
include
the second.
***>>
c3a_box_append_pt <<***
******
Summary ******
#include
<c3adefs.h>
void
c3a_box_append_pt ( box, pt );
******
Description ******
This
routine expands a bounding box to include a point.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box | the box to expand |
------------------------------------------------------------------------------
|
PT3 | pt | a point |
------------------------------------------------------------------------------
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1, p;
C3_BOX box0;
c3v_set ( 2.0, 3.0, 0.0, p0 );
c3v_set ( 5.0, 6.0, 5.0, p1 );
box0 = c3a_box ( p0, p1 );
c3v_set ( 7.0, 8.0, 7.0, p );
c3a_box_append_pt ( box0, p );
c3a_free_box ( box0 );
}
This
program expands a bounding box to include a point.
***>>
c3a_box_copy <<***
******
Summary ******
#include
<c3adefs.h>
void
c3a_box_copy ( box0, box1 );
******
Description ******
This
function copies a bounding box.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box0 | the box to copy |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
C3_BOX | box1
| the copy; this box must be |
| | | created by the
caller |
------------------------------------------------------------------------------
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1, origin;
C3_BOX box0, box1 ;
c3v_set ( 0.0, 0.0, 0.0, origin );
box1 = c3a_box ( origin, origin );
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box0 = c3a_box ( p0, p1 );
c3a_box_copy ( box0, box1 );
c3a_free_box ( box0 );
c3a_free_box ( box1 );
}
This
program makes box1 a copy of box0.
***>>
c3a_box_init_pt <<***
******
Summary ******
#include
<c3adefs.h>
void
c3a_box_init_pt ( box, pt );
******
Description ******
This
function initializes the lower left back and upper right front corners
of a
bounding box to the same point. The
result is a rectangular prism with
zero
volume.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box | the box to initialize |
------------------------------------------------------------------------------
|
PT3 | pt | the point to initialize the |
| | | box to |
------------------------------------------------------------------------------
******
Example ******
#include
<c3adefs.h>
#include
<c3vdefs.h>
void
main()
{
PT3 p;
C3_BOX box = c3a_box ( NULL, NULL );
c3v_set ( 2.0, 3.0, 0.0, p );
c3a_box_init_pt ( box, p );
c3a_free_box ( box );
}
This
program creates a bounding box with both corners (2.0,3.0,0.0).
***>>
c3a_box_overlap <<***
******
Summary ******
#include
<c3adefs.h>
BOOLEAN
c3a_box_overlap ( box1, box2 );
******
Description ******
This
routine determines if two bounding boxes overlap.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box1, box2 | the bounding boxes to test |
| | | for overlap |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is TRUE if the boxes overlap; it is FALSE otherwise.
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1;
C3_BOX box0, box1;
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box0 = c3a_box ( p0, p1 );
c3v_set ( 3.0, 4.0, 2.0, p0 );
c3v_set ( 7.0, 8.0, 6.0, p1 );
box1 = c3a_box ( p0, p1 );
if ( c3a_box_overlap ( box0, box1 ) )
printf ( "boxes overlap\n"
);
c3a_free_box ( box0 );
c3a_free_box ( box1 );
}
This
program tests two bounding boxes to determine if they overlap, and
returns
TRUE in this particular example.
***>>
c3a_box_union <<***
******
Summary ******
#include
<c3adefs.h>
void
c3a_box_union ( box1, box2, box );
******
Description ******
This
function computes the bounding box that encloses two bounding boxes.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box1, box2 | the boxes to enclose |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
C3_BOX | box | the box that contains
both |
| | | input boxes |
------------------------------------------------------------------------------
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1;
C3_BOX box0, box1, box;
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box0 = c3a_box ( p0, p1 );
c3v_set ( 3.0, 4.0, 2.0, p0 );
c3v_set ( 7.0, 8.0, 6.0, p1 );
box1 = c3a_box ( p0, p1 );
box = c3a_box ( NULL, NULL );
c3a_box_union ( box0, box1, box );
c3a_free_box ( box );
c3a_free_box ( box0 );
c3a_free_box ( box1 );
}
This
program computes the bounding box that encloses two boxes.
***>>
c3a_box_w_overlap <<***
******
Summary ******
#include
<c3adefs.h>
BOOLEAN
c3a_box_w_overlap ( box1, box2, w );
******
Description ******
This
function determines if two boxes are less than a given distance apart.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box1, box2 | the boxes to test |
------------------------------------------------------------------------------
|
REAL | w | the separation
distance |
------------------------------------------------------------------------------
******
Return Value ******
If the
boxes overlap or are separated by a distance less than the given
distance,
the return value is TRUE; otherwise it is FALSE.
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1;
C3_BOX box0, box1;
REAL w = 1.0;
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box0 = c3a_box ( p0, p1 );
c3v_set ( 5.5, 6.5, 4.5, p0 );
c3v_set ( 7.0, 8.0, 6.0, p1 );
box1 = c3a_box ( p0, p1 );
if ( c3a_box_w_overlap ( box0, box1, w ) )
printf ( "boxes overlap or are
less " );
printf ( "than 1 unit
apart\n" );
c3a_free_box ( box0 );
c3a_free_box ( box1 );
}
This
program determines if two bounding boxes overlap or are less than 1
unit
apart.
***>>
c3a_free_box <<***
******
Summary ******
#include
<c3adefs.h>
void
c3a_free_box ( box );
******
Description ******
This
function frees a bounding box.
******
Input ******
------------------------------------------------------------------------------
|
C3_BOX | box | the box to free |
------------------------------------------------------------------------------
******
Example ******
#include
<c3vdefs.h>
#include
<c3adefs.h>
void
main()
{
PT3 p0, p1;
C3_BOX box0;
c3v_set ( 2.0, 3.0, 1.0, p0 );
c3v_set ( 5.0, 6.0, 4.0, p1 );
box0 = c3a_box ( p0, p1 );
c3a_free_box ( box0 );
}
This
program creates and frees a bounding box.
@NEWPAGE
=
***>>
c3c_approx <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_approx ( curve, parm1, current_parm,
max_dist, dir, pt_buffer,
parm_buffer,
buf_size, index );
******
Description ******
This
function computes the vertices of a polygon that approximates a curve.
The
polygon does not deviate from the curve by more than a specified
distance.
If dir
is TRUE, the polygon follows the curve away from its start point and
toward
its end point; otherwise the polygon follows
the curve in the
opposite
direction.
The
vertices of the polygon are stored in a caller-supplied array of points.
If the
number of points required for an approximating polygon is greater
than
the number that will fit into the array, this function fills the array,
marks
the location of the last point with
current_parm, and returns FALSE to
indicate
that the entire polygon was not
computed. The next call to this
function
begins the approximating polygon at the
location specified by
current_parm. Thus, if a polygon cannot be generated
with one call, it can
be
generated with successive calls.
Prior
to generating a polygon with this function, the argument current_parm
should
be initialized with the c3c_approx_init
function.
This
function optionally computes the curve parameters that correspond to
the
vertices of the polygon.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve from which the |
| | | polygon is to be |
| |
| constructed |
------------------------------------------------------------------------------
|
PARM | parm1 | ending parameter value;
the |
| | | polygon will end at the
|
| | | point corresponding to
this |
| | | parameter value; if
this |
| | | argument is NULL, the
|
| | | polygon ends at the
end |
| | | point of the curve |
------------------------------------------------------------------------------
|
PARM |
current_parm | on input, this
argument |
| | | marks the location of
the |
| | | first point to be
computed; |
| | | on output, this
argument |
| | | marks the location of
the |
| | | last point computed;
this |
| |
| parameter must be |
| | | initialized with |
| | | c3c_approx_init
before |
| | | starting the approximation |
------------------------------------------------------------------------------
|
REAL | max_dist | the maximum allowed chordal |
| | | deviation of the polygon
|
| | | from the curve |
------------------------------------------------------------------------------
|
BOOLEAN | dir | the direction to follow;
if |
| | | TRUE, the polygon
follows |
| | | the "natural" direction of |
| | | the curve; if FALSE,
the |
| | | polygon runs
against this |
| | | direction |
------------------------------------------------------------------------------
| PT3
* | pt_buffer
| an array of buf_size points; |
| | | if this argument is NULL, |
| | | the points are not
computed |
------------------------------------------------------------------------------
| PARM
* | parm_buffer | an array of buf_size |
| | | parameter records; if
this |
| | | argument is NULL, the |
| | | parameters are not
computed |
------------------------------------------------------------------------------
|
INT | buf_size | the number of points and/or |
| | | parameters that can be held
|
| | | by the provided
arrays |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
| INT
* | index | the number of points
and/or |
| | | parameters that
were |
| | | computed; this number is |
| | | buf_size if the arrays
are |
| | | completely filled; it is
|
| | | less than buf_size if
the |
| | | number of points
required to |
| | | approximate the curve is |
| |
| less than buf_size; this |
| | | argument is passed by |
| | | reference |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the polygon has reached the point on the curve
where
the polygon should end; otherwise it returns FALSE.
******
Example ******
#include
<c3cdefs.h>
#include
<dmldefs.h>
#define
BUF_SIZE 50
DML_LIST
polygonize_curve ( curve, max_dist )
C3_CURVE
curve ;
REAL
max_dist ;
{
PT3 pt_buffer[BUF_SIZE] ;
DML_LIST pt_list = dml_create_list();
PARM_S curve_parm ;
BOOLEAN end_bit, dir = FALSE;
INT index, i ;
c3c_approx_init ( curve, NULL,
&curve_parm, dir ) ;
do {
end_bit = c3c_approx ( curve, NULL,
&curve_parm, max_dist,
dir, pt_buffer, NULL,
BUF_SIZE, &index ) ;
for ( i=0 ; i < index ; i++ )
dml_append_data ( pt_list,
pt_buffer[i] ) ;
} while ( !end_bit ) ;
return ( pt_list ) ;
}
@NEWPAGE
=
***>>
c3c_approx_init <<***
******
Summary ******
#include
<c3cdefs.h>
void
c3c_approx_init ( curve, parm0, start_parm,
dir );
******
Description ******
This
function initializes the parameter record used in calls to c3c_approx
to mark
the "current" point of a polygon.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | the curve that will be |
| | | approximated |
------------------------------------------------------------------------------
|
PARM | parm0 | the parameter value of the |
| | | point where the
polygon |
| | | should begin; if this |
| | | parameter is NULL,
the |
| | | polygon begins at the
start |
| | | or end point of the curve, |
| | | depending on the value
of |
| | | dir |
------------------------------------------------------------------------------
|
BOOLEAN | dir | the direction that the |
| | | polygon will follow
along |
| | | the curve; if TRUE, the |
| | | polygon will follow
the |
| |
| "natural" direction of the
|
| | | curve; if FALSE, it
will |
| | | follow the opposite |
| | | direction |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PARM | start_parm | the parameter record |
| | | initialized to the
parameter |
| | | value of the start point of |
| | | the polygon. |
------------------------------------------------------------------------------
******
Example ******
See
example for the routine c3c_approx.
***>>
c3c_arc_angle <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_arc_angle ( curve, parm, angle ) ;
******
Description ******
This
function computes the arc angle that corresponds to a specified curve
parameter. The angle is expressed relative to the start
of the arc, and in
radians.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | an arc |
------------------------------------------------------------------------------
|
PARM | parm | a curve parameter |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
| REAL
* | angle | the angle in radians that |
| | | corresponds to the
curve |
| | | parameter |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is TRUE if the input curve is an arc; it is FALSE
otherwise.
******
Example ******
#include
<c3cdefs.h>
void pr_arc_angle
( arc, parm )
C3_CURVE
arc ;
PARM
parm ;
{
REAL angle;
if ( c3c_arc_angle ( arc, parm, &angle
) )
printf ( "angle: %lf\n",
angle );
else printf ( "Curve is not an
arc\n" ) ;
}
This
subroutine prints the arc angle corresponding to a curve parameter.
***>>
c3c_arc_parm <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_arc_parm ( curve, angle, parm ) ;
******
Description ******
This
function computes the curve parameter that corresponds to an arc angle.
The arc angle is measured relative to the
start of the arc.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | an arc |
------------------------------------------------------------------------------
|
REAL | angle | an arc angle expressed in |
| | | radians |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PARM | parm | the curve parameter that |
| | | corresponds to the angle |
------------------------------------------------------------------------------
******
Return Value ******
The
return value is TRUE if the input curve is an arc; it is FALSE
otherwise.
******
Example ******
#include
<c3cdefs.h>
void
pr_arc_parm ( arc, angle )
C3_CURVE
arc ;
REAL
angle ;
{
PARM_S parm_s;
PARM parm = &parm_s;
if ( c3c_arc_parm ( arc, angle, parm ) )
printf ( "parameter:
%lf\n", PARM_T(parm) );
else printf ( "Curve is not an
arc\n" ) ;
}
This
subroutine prints the curve parameter corresponding to an arc angle.
@NEWPAGE
=
***>>
c3c_closed <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_closed ( curve );
******
Description ******
This
function determines if a curve forms a closed loop, i.e. its start and
end
points are coincident.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the curve is closed.
Otherwise it returns
FALSE.
******
Example ******
#include
<c3cdefs.h>
void
check_closed ( curve )
C3_CURVE
curve ;
{
if ( c3c_closed ( curve ) )
printf ( "The curve is
closed.\n" ) ;
else
printf ( "The curve is not
closed.\n" ) ;
}
This
routine checks if a given curve is closed, and prints out an
appropriate
message.
@NEWPAGE
=
***>>
c3c_curves_plane <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_curves_plane ( curvelist, normal,
dist_ptr, status_ptr );
******
Description ******
This
function computes the normal vector and distance from the origin of the
plane
in which a set of curves lie. If the
curves are not on a plane, FALSE
is
returned.
******
Input ******
------------------------------------------------------------------------------
|
DML_LIST | curvelist | a list of curves |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | normal | the normal vector of the |
| | | plane that the curves
lie on |
------------------------------------------------------------------------------
| REAL
* | dist_ptr | the distance from the origin |
| | | to the plane along
the |
| | | normal direction |
------------------------------------------------------------------------------
|
C3_PLANE_STATUS * | status_ptr | status of plane computation; |
| | | may be NULL |
------------------------------------------------------------------------------
The
argument status will be set to one of the
following values when this
routine
returns:
______________________________________________________________________________
| Value | Meaning |
|----------------------------------------------------------------------------|
|
C3_PLANE_DET |
the curves determine a plane |
|
C3_PLANE_OVER_DET |
the curves are not planar |
|
C3_PLANE_UNDER_DET |
the curves do not determine a |
| | unique
plane |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was successful. Otherwise it
returns
FALSE.
******
Example ******
#include
<c3cdefs.h>
void
print_plane ( curves )
DML_LIST
curves ;
{
PT3 n;
REAL d;
C3_PLANE_STATUS status;
if ( !c3c_curves_plane ( curves, n,
&d, &status ) )
printf ( "Curves are not in one
plane.\n" ) ;
else
printf ( "normal dist: %lf %lf
%lf %lf\n",
PT3_X(n), PT3_Y(n), PT3_Z(n),
d );
}
This
routine prints out the normal vector and distance from the origin of
the
plane in which a set of curves lie.
@NEWPAGE
=
***>>
c3c_ept0 <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_ept0 ( curve, pt );
******
Description ******
This
function evaluates the start point of a curve.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | pt | the start point of the
input |
| | | curve |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_ept0 ( a, ept0 )
PT3 *a
; /* four point array */
PT3
ept0 ;
{
C3_CURVE curve ;
curve = c3d_spline ( a, 4 );
if ( !c3c_ept0 ( curve, ept0 ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline passing through four given points, and then
computes
the start point of this curve.
@NEWPAGE
=
***>>
c3c_ept1 <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_ept1 ( curve, pt );
******
Description ******
This
function evaluates the end point of a curve.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | pt | the end point of the
curve |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_ept1 ( a, ept1 )
PT3 *a
; /* four point array */
PT3
ept1 ;
{
C3_CURVE curve ;
curve = c3d_spline ( a, 4 ) ;
if ( !c3c_ept1 ( curve, ept1 ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline with four through points, and then computes
the end
point of this curve.
@NEWPAGE
=
***>>
c3c_ept_tan0 <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_ept_tan0 ( curve, pt, tan_vec );
******
Description ******
This
function evaluates the coordinate and the tangent vector at the start
point
of a curve.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | pt | the start point of the |
| | | curve; if this argument
is |
| | | NULL, the start point is |
| | | not computed |
------------------------------------------------------------------------------
|
PT3 | tan_vec | the start tangent of the |
| | | curve; if this argument
is |
| | | NULL, the start tangent is |
| |
| not computed |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3cdefs.h>
void
spline4_ept_tan0 ( a, pt0, tan0 )
PT3 *a
; /* four point array */
PT3
pt0, tan0 ;
{
C3_CURVE curve ;
curve = c3d_spline ( a, 4 ) ;
if ( !c3c_ept_tan0 ( curve, pt0, tan0 ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline passing through four given points, and then
computes
its start point and the tangent vector at this point.
@NEWPAGE
=
***>>
c3c_ept_tan1 <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_ept_tan1 ( curve, pt, tan_vec );
******
Description ******
This
function evaluates the coordinates and the tangent vector at the end
point
of a curve.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | pt | the end point of the
curve; |
| | | if this argument is
NULL, |
| | | the end point is not |
| | | computed |
------------------------------------------------------------------------------
|
PT3 | tan_vec
| the end tangent of the |
| | | curve; if this argument
is |
| | | NULL, the end tangent is |
| | | not computed |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_ept_tan1 ( a, pt1, tan1 )
PT3 *a;
PT3
pt1, tan1 ;
{
C3_CURVE curve ;
curve = c3d_spline ( a, 4 );
if ( !c3c_ept_tan1 ( curve, pt1, tan1 ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline with four through points, and then computes
its end
point and the tangent vector at this point.
@NEWPAGE
=
***>>
c3c_etan0 <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_etan0 ( curve, tan_vec );
******
Description ******
This
function evaluates the start tangent vector of a curve. This vector is
not
necessarily a unit vector.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | tan_vec | the start tangent of the |
| | | curve |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_tan0 ( a, tan0 )
PT3 *a
; /* four point array */
PT3
tan0 ;
{
C3_CURVE curve ;
curve = c3d_spline ( a, 4 ) ;
if ( !c3c_etan0 ( curve, tan0 ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This routine
creates a spline with four through points, and
then computes
tangent
vector at the start point of this curve.
@NEWPAGE
=
***>>
c3c_etan1 <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_etan1 ( curve, tan_vec );
******
Description ******
This
function evaluates the end tangent vector of a
curve. This vector is
not
necessarily a unit vector.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve
| a 3D curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
| PT3 | tan_vec | the end tangent of the
curve |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_tan1 ( a, tan1 )
PT3 *a
; /* four point array */
PT3
tan1 ;
{
C3_CURVE curve ;
curve = c3d_spline ( a, 4 ) ;
if ( !c3c_etan1 ( curve, tan1 ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline with four through points, and then computes
tangent
vector at the end point of this curve.
@NEWPAGE
=
***>>
c3c_eval <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_eval ( curve, parm, p, x );
******
Description ******
This
routine evaluates a point on a curve, as well as the derivatives of the
curve
at that point of up to a given order p.
The location where the
evaluation
should be performed is specified with a
curve parameter record.
The
results of the computations are stored in an array of points which has
dimension
p+1 and is supplied by the caller.
The
derivatives are computed with respect to the parameterization of the
curve,
and therefore are particularly useful for applications based on the
Newton-Raphson
method.
******
Input ******
------------------------------------------------------------------------------
| C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
|
PARM | parm | the parameter specifying
the |
| | |
location on the curve where |
| | | the evaluation should
be |
| | | performed |
------------------------------------------------------------------------------
|
INT | p | the maximun
derivative |
| | | order; 0 means compute
the |
| | | coordinates of the
point |
| | | only; 1 means compute
the |
| | | coordinates and the first
|
| | | derivative |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | x[0] | the point on the curve |
------------------------------------------------------------------------------
|
PT3 |
x[1],...,x[p] | the derivatives of
the curve |
| | | at x[0] |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_mid_pt ( a, mid_pt )
PT3 *a
; /* four point array */
PT3
mid_pt[3] ;
{
PARM_S parm ;
C3_CURVE curve ;
curve = c3d_spline ( a, 4 ) ;
PARM_SET ( 0.5 * C3_CURVE_T1(curve),
&parm ) ;
if ( !c3c_eval ( curve, &parm, 2,
mid_pt ) )
printf ( "Evaluation
failed.\n" ) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline that passes through four points. Then
it
computes
the midpoint of the spline, as well as the first and second
derivatives
at that point.
@NEWPAGE
=
***>>
c3c_eval_pt <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_eval_pt ( curve, parm, pt );
******
Description ******
This
routine evaluates the point on a curve corresponding to a curve
parameter
record.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
|
PARM | parm | the curve parameter |
| | | specifying the location
of |
| | | the point on the
curve |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | pt | the point on the curve
|
| | | corresponding to the
curve |
| | | parameter |
------------------------------------------------------------------------------
******
Return Value ******
This
function returns TRUE if the computation was
successful. Otherwise it
returns
FALSE.
******
Example ******
#define
SPLINE
#include
<c3ddefs.h>
#include
<c3cdefs.h>
void
spline4_mid_pt ( a, mid_pt )
PT3 *a
; /* four point array */
PT3
mid_pt ;
{
PARM_S parm ;
C3_CURVE curve ;
curve = c3d_spline ( a, 4 ) ;
PARM_SET ( 0.5 * C3_CURVE_T1(curve),
&parm ) ;
if ( !c3c_eval_pt ( curve, &parm,
mid_pt ) )
printf ( "Evaluation failed.\n"
) ;
c3d_free_curve ( curve ) ;
}
This
routine creates a spline passing through four points, and then computes
midpoint
of this curve.
@NEWPAGE
=
***>>
c3c_eval_pt_tan <<***
******
Summary ******
#include
<c3cdefs.h>
BOOLEAN
c3c_eval_pt_tan ( curve, parm, pt,
tan_vec );
******
Description ******
This
function evaluates the coordinates and the tangent vector of a point on
a
curve. The location of the point is
specified with a curve parameter
record.
******
Input ******
------------------------------------------------------------------------------
|
C3_CURVE | curve | a 3D curve |
------------------------------------------------------------------------------
|
PARM | parm | a curve parameter record |
| | | specifying the
location on |
| | | the curve where the |
| | | evaluation should
be |
| | | performed |
------------------------------------------------------------------------------
******
Output ******
------------------------------------------------------------------------------
|
PT3 | pt | the point on the curve |
| | | corresponding to the
curve |
| | | parameter record; if this |
| | | argument is NULL, the
point |
| | | is not computed |
------------------------------------------------------------------------------
|
PT3 | tan_vec | the tangent vector at the |
| | | point corresponding
to the
|
| |