All Frameworks  Class Hierarchy  This Framework  Indexes

SPAds Global Function DM_set_pt_xyz

Sets the image space point for a constraint or control point.

Role: This function sets the location for an image_point or a control point of the tag object identified by the input tag value.

When p1 is a reference to a NULL pointer, the tag's image point is set to the value p0. To help support mouse pick-and-drag, this subroutine can be used to compute the tag's new image point location from an image space line. The image space line or iline, is specified as the line which runs through p0 and p1. Usually this line will be generated from the window system's pick-ray and pick-point for a user-generated pick event. Four different new point calculations are supported based on the dir_flag, pt_index and tag_type values.

When pt_index equals DM_BASE_PT and dir_flag equals 1, the new image point is the intersection between the image line and the plane parallel to the xy axis that contains the current image point location. This is good for dragging a point in its xy plane.

When pt_index equals DM_BASE_PT and dir_flag equals 2, the new image point is the point on a line parallel to the z axis containing the current image point location that is nearest to the input image line. This is good for dragging a point along its z axis.

For objects with vectors (such as tangent point constraints and vector loads) the input pt_index value specifies whether the vector's base point or one of the end points is moved. The object's vector runs from the vector's base point to its end point.

When pt_index equals DM_BASE_PT, the vector's base point and end point are both modified so that the vector's magnitude and direction remains constant while its position is modified. When pt_index equals any option that specifies an end point, e.g., DM_TANG1_LEG, the vector's end point is modified while the base point remains fixed. The vector's position remains constant while its magnitude and direction are modified.

When the pt_index corresponds to a vector end point and dir_flag equals 1, the new image position of the end point is the intersection of the input image line and a hemisphere centered on the point constraint's base point with a radius equal to the current tangent vector's magnitude. This is good for rotating a vector by dragging.

When pt_index corresponds to one of the vector end points and dir_flag equals 2, the new image position of the end point is the point on a line running through the vector's base point and end point closest to the input image line. This is good for changing the magnitude of a vector by dragging.

Tag numbers less than -500 are used to change control point locations. When moving a control point location, the control point on the active deformable model is moved.

When pt_index equals DM_CURV1_LEG or DM_CURV2_LEG the vector is constrained to remain perpendicular to the point constraint's tangent vector. In this case the dir_flag equals 1 option will only rotate the vector in the plane perpendicular to the tangent vector.

When pt_index equals DM_TANG1_LEG or DM_TANG2_LEG and the object being manipulated is a pt_cstrn then the point constraint's DM_CURV1_LEG and DM_CURV2_LEG values are updated to keep the curvature vector perpendicular to the tangent and to keep the curvature value a constant. The osculating plane will be reoriented in an unspecified, but minimal, fashion. Modify the DM_CURV1_LEG or DM_CURV2_LEG plane as desired.

When dir_flag equals 0, no constraints are applied to the input parameter and it is the responsibility of the calling program to make supply a valid position, e.g., the normal vector is perpendicular to the tangent and so on.

To summarize, for tag objects with vectors and a pt_index equal to 1:

dir_flag == 1	Sets the point closest to the pick ray on a base point centered hemisphere (for rotation).
dir_flag == 2	Sets the point closest to the pick ray on the base point, end point line (base_pt, end_pt) line (for scaling).

For cases where pt_index is equal DM_BASE_PT, or the index for a spring_set or a control point tag:

dir_flag == 1	Sets the point at the intersection of the pick ray and the image point's xy plane (move in xy plane).
dir_flag == 2	Sets the point closest to the pick ray on the image point's z_vec line (move in z direction).

These four cases are intended to allow an application interface to move an xyz point so that it tracks a 2D mouse location and moves in three dimensional space in a reasonable fashion.

Note:

- Use DM_END_LEG for the vector loads,

- Use DM_TANG_LEG for the pt_cstrn on a curve tangent end_pt,

- Use DM_TANG1_LEG for the pt_cstrn on a surface's first tangent end_pt,

- Use DM_TANG2_LEG for the pt_cstrn on a surface's second tangent end_pt,

- Use DM_NORM_LEG for the pt_cstrn on a surface's normal vector end_pt,

- Use DM_CURV_LEG for the pt_cstrn on a curve's curvature vector end_pt,

- Use DM_CURV1_LEG for the pt_cstrn on a surface's first curvature end_pt,

- Use DM_CURV2_LEG for the pt_cstrn on a surface's second curvature end_pt,

- Use DM_BINORM_LEG for the pt_cstrn on a curve's binormal vector end_pt.

Setting the curvature constraint_value from the image_pt when constraining a surface (domain_dim = 2) is ambiguous. There are two solutions for k and n which satisfy the relation,

 curv_pt = k * n and curv_pt = -k *-n 

The first solution, k positive, will have a surface concave in the direction of the surface normal n. The second solution, k negative, will have a surface convex in the direction of the surface normal n. For curves, k is always positive. When setting the curv_pt location directly (dir_flag = 0) one must tell the library which case to use. Otherwise, it chooses to preserve the sign of the curvature when rotating the curvature vec (dir_flag = 1), and chooses to preserve the direction of the surface norm_val when lengthening the vector (dir_flag = 2).

Many of a pt_cstrn's constraint values are related. This function can update the pt_cstrn's constraint values one at a time, or as a convenience cascade a change to other cstrn values to make sure they are all in a valid state. When cascade_flag == 0, only the image_pt and its related cstrn_value indicated by the pt_index value will be updated. In this case the application will have to ensure that all the pt_cstrn value relationships are satisfied prior to calling DM_solve() otherwise a conflicting constraint may occur.

When cascade_flag = 1, all related cstrn_vals will be modified by a minimum amount to preserve the cstrn_val relationships. The angle between tangent vectors for point constraints on surfaces will be preserved. When cascade_flag == 2, all related cstrn_vals will be modified by a minimum amount, but the angle between tangent vectors for constraint points on surfaces is allowed to vary.

The pt_cstrn rules include the following. Only those rules that use properties which are being constrained by the pt_cstrn's behavior (see DM_set_cstrn_behavior()) need to be enforced. Unconstrained properties will satisfy these rules after the next call to DM_solve().

Rules enforced on the constraint values for DS_pt_cstrns.

1. for curves in 2d
1. tang1_val perp to norm_val
2. curv1_val not negative
3. norm_val is an unit vector
2. for curves in 3d
1. tang1_val perp to norm_val
2. norm_val perp to binorm_val
3. binorm_val perp to tang1_val
4. curv1_val not negative
5. norm_val is an unit vector
6. binorm_val is an unit vector
3. for surfaces
1. domain1_dir is an unit vector
2. domain2_dir is an unit vector
3. domain1_dir not parallel to domain2_dir
4. tang1_val perp to norm_val
5. tang2_val perp to norm_val
6. tang1_val, tang2_val, and norm_val make a right hand coordinate system (note depends domain1_dir and domain2_dir)
7. norm_val is an unit vector
8. no restrictions on curv1_val or curv2_val

Errors:

DM_NO_ROOT_DMOD

The root deformable model cannot be NULL on input.

DM_BAD_DIR_FLAG_VALUE

The value of dir must be 0, 1, or 2.

DM_NULL_INPUT_PTR

When the dir is 1 or 2, P1 cannot be NULL on entry.

DM_NULL_INPUT_PTR

The value of P0 or p1 cannot be NULL on entry

DM_TAG_OBJECT_NOT_FOUND

The input tag cannot identify a deformable model, a load, a spring, a spring set, an attractor object, or a constraint in the model hierarchy.

DM_NO_XYZ_PT_FOR_TAG_OBJ

The identified tag object has no distinct xyz point to report dyn_loads, dist_press, crv_loads and crv_cstrns, or deformable model.

DM_BAD_PT_INDEX_VALUE

The spring_set and pt_index must be within the point count range.

DM_PARALLEL_PROJECT_DIR

The the projection direction (i.e., the z axis, the xy plane, or the direction of a tangent vector) cannot be parallel to the image line. If executed, the projection would move the image_pt out to infinity.

Effect: Changes model

Parameters:

rtn_err

out: 0=success or negative err code.

dmod

in: member of target dmod hierarchy to search.

tag

in: unique tag identifier to match.

pt_index

in: index of tag's image_pt to update one of DM_BASE_PT DM_END_LEG DM_TANG_LEG DM_TANG1_LEG DM_TANG2_LEG DM_NORM_LEG DM_CURV1_LEG DM_CURV2_LEG DM_BINORM_LEG or a control point tag or an id number in a spring set.

p0

new ipt or p0 of iline=p0+u*(p1-p0) [not-nested] sized:[image_dim].

p1

in: NULL or p1 of iline=p0+u*(p1-p0) [not-nested] sized:[image_dim].

dir_flag

in: 0=let image_pt equal P0, for pt_index == DM_BASE_PT 1=move parallel to xy plane, 2=move parallel to z axis. else 1=rotate current vector, 2=change vector magnitude.

cascade_flag

in: 2=move tangent vecs independently, but update normal vecs. 1=update related pt_cstrn values and image_pts. 0=don't.

curvature_sign

in: used when dir_flag ==0 && domain_dim==2 && PT_index==PST_CURV1 or PST_CURV2. +1: use curv_pt = k * n, (k positive), -1: use curv_pt = -k * -n, (k negative), to solve for k and n vals.

sdmo

in:SDM_options pointer.

Copyright (c) 1989-2007 by Spatial Corp. All rights reserved.