Adding and deleting geometric objects

The geometric solver mainly works with geometric objects, so, in starting to create the constraint system, the application declares the geometric objects that will become constraint arguments in the constraint system.

Every geometric object declared in the constraint system will have its unique identifier – a GCM_geom descriptor. Its geometric type (GCM_g_type) remains unchanged throughout the object’s life. API C3D Solver calls that add geometric objects to the system are described below.

A point is added by calling

GCM_geom GCM_AddPoint(GCM_system gSys, const MbCartPoint3D & pVal)

The function returns a descriptor of the geometric point of the GCM_POINT type that belongs to the gSys geometric constraint system. The pVal parameter sets the start values of <x,y,z> point coordinates.

To create geometric objects of other types, including a point, you should fill the GCM_g_record] data structure which is a unified record for any geometry type supported by the solver. This structure value is the input value of function

GCM_geom GCM_AddGeom(GCM_system gSys, const GCM_g_record & gRec)

The result of the call is the descriptor of the geometric object registered in the gSys system. Geometric object parameters are specified by fields of the GCM_g_record structure:

  • gRec.type sets the geometric type of the object (GCM_g_type);

  • gRec.origin sets the objects position and its LCS origin;

  • gRec.axisZ sets the Z axis vector of LCS;

  • gRec.axisX sets the X axis vector of LCS;

  • gRec.axisY sets the Y axis vector of LCS;

  • gRec.radiusA and gRec.radiusB set scalar parameters of radial objects.

Function

GCM_g_record GCM_Point(const MbCartPoint3D &)

performs actual conversion of the value of 3D point coordinates from the MbCartPoint3D data type into GCM_g_record, perceived by the GCM_AddGeom function.

GCM_g_record GCM_Line(const MbCartPoint3D & org, const MbVector3D & axisZ)

returns the line record based on a point and directing vector.

GCM_g_record GCM_Plane(const MbCartPoint3D & org, const MbVector3D & axisZ)

returns the record of a plane defined by a normal point and vector.

Function for creating a cone record:

GCM_g_record GCM_Cone(const MbCartPoint3D & centre, const MbVector3D & axis
                                  , double radiusA
                                  , double radiusB)

Input parameters:

  • centre – center of the base circle of the cone,

  • axis – direction vector of the cone axis,

  • radiusA – cone base radius,

  • radiusB – cone section radius (lesser radius).

Cone parameters are assumed to describe a virtual truncated cone whose height is always equal to a length unit, i.e. there is a unit distance between the cross section of radiusA and the radiusB section (see figure in Table 32.8.1.).

Function for creating a cylinder record:

GCM_g_record GCM_Cylinder(const MbCartPoint3D & centre, const MbVector3D & axis
                                    , double radius)

Input parameters:

  • centre – a point on the cylinder axis;

  • axis – direction vector of the cone axis;

  • radius – cylinder radius.

Function for creating a circle record:

GCM_g_record GCM_Circle(const MbCartPoint3D & centre, const MbVector3D & axis
                                    , double radius)

Input parameters:

  • centre – circle center coordinates;

  • axis – direction of the circle axis;

  • radius – circle radius.

Function for creating a toroid record:

GCM_g_record GCM_Torus(const MbCartPoint3D & centre, const MbVector3D & axis
                                   , double majorR
                                   , double minorR)

Input parameters:

  • centre – toroid center coordinates;

  • axis – direction of the toroid revolution axis,

  • majorR – distance from the toroid center to the center of the generating circle of the toroid;

  • minorR – radius of the generating circle of the toroid.

Function for creating a sphere record:

GCM_g_record GCM_Sphere(const MbCartPoint3D & centre, double radius)

Input parameters:

  • centre – sphere center;

  • radius – sphere radius.

Function for creating a rectangular right-handed coordinate system LCS:

GCM_g_record GCM_SolidLCS(const MbCartPoint3D & org, const MbVector3D & axisZ
                                   , const MbVector3D & axisX)

Input parameters:

  • org – coordinate system origin;

  • axisZ – Z unit vector;

  • axisX – X unit vector;

The result of the function is the LCS record in the form of <O Z X Y>, where axis Z is directed by vector product X Y that corresponds to the right-handed orientation of X-Y-Z . The geometric type of the LCS record is GCM_LCS.

Another method for creating the LCS record has the same name but its argument is MbPlacement3D:

GCM_g_record GCM_SolidLCS(const MbPlacement3D &)

This method allows creating both right-handed and left-handed CS.

The result returned by the GCM_SolidLCS function is used to create a solid body (cluster) in the constraint system by calling GCM_AddGeom or GCM_SubGeom.

You can use the following call to create an emptyGCM_g_record record that can be used to create a default value:

GCM_g_record GCM_NullGeom(void)

Below is the code fragment that demonstrates creating a system that includes the sph sphere with its center in the CS origin and the cylinder cyl with its center coordinates <10, 0, 0> and oriented along the Z axis.

GCM_system gSys = GCM_CreateSystem();
const MbCartPoint3D cylPos(10.0, 0.0, 0.0);
/*
Register two geoms, sphere and cylinder.
*/
GCM_geom sph = GCM_AddGeom(gSys, GCM_Sphere(MbCartPoint3D::origin, 10.0));
GCM_geom cyl = GCM_AddGeom(gSys, GCM_Cylinder(cylPos, MbVector3D::zAxis, 10.0));
...
...
/*
Finalize the constraint system to free its located memory.
*/
GCM_RemoveSystem(gSys);

In addition to the GCM_AddGeom call, the solver provides for another method to register geometric objects providing for solid body abstraction – geometrically rigid sets with their own LCS. Such subsets are called clusters. To create a cluster, declare its LCS using the following query:

GCM_geom lcs = GCM_AddGeom(gSys, GCM_SolidLCS(org, axisZ, axisX));

Values org, axisZ, axisX set the cluster position and orientation (its LCS). The resulting lcs descriptor will define the LCS of the geometrically rigid set whose elements are declared by the following call:

GCM_geom GCM_SubGeom(GCM_system gSys, GCM_geom lcs, const GCM_g_record & gRec)

Input parameters:

  • gSys – geometric constraint system;

  • lcs – cluster LCS descriptor;

  • gRec – record of geometric parameters of the object defined in the cluster LCS.

The function returns the descriptor of the geometric object that belongs to the cluster. A specific feature of the object that belongs to the cluster is that its location in space depends on the cluster’s LCS. Thus, the dependent object changes its location together with the cluster’s LCS. This is its key difference from objects created using the GCM_AddGeom method. Handling clusters is described in more detail in Geometric scene clustering, assembly modeling.

Geometric objects returned by GCM_SubGeom and GCM_AddGeom functions may participate in constraints and dimensions, i.e. they can be used as Constraint argument.

Geometric objects are deleted by the following call:

void GCM_RemoveGeom(GCM_system gSys, GCM_geom g)

This method deletes the geometric object from the system and renders its descriptor g invalid. If a geometric object remains an argument of one constraint at the moment when the system is called, it actually remains in the system, but it will be inevitably deleted after deleting the last constraint associated with this object. Therefore, the GCM API user can release a geometric object when it is no longer needed for the application without paying attention to any binding constraints.