[steptools.com] [Documentation] [STEP AP Helper Library]

Overview

These functions interface the STEP axis placements, points, and such with the RoseMath transform and vector operations, as well as provide convenience operations on the STEP geometric definitions.

All definitions are in the stix_geometry.h header file.

stix_find_nested_repitems()

void stix_find_nested_repitems(
	stp_representation * rep, 
	ListOfstp_representation_item * nested
	);

The stix_find_nested_repitems() function builds a list containing all representation items owned by a representation. It recursively follows references from item to item so the list will contain the top level solid, then faces, curves, and so on down to cartesian points and directions. The function does not follow mapped items or styled items because they lead to other representations.

stix_get_cone_angle()

double stix_get_cone_angle(
        stp_conical_surface * cone,
        stp_representation * rep,
        RoseUnit angle_unit = roseunit_rad
        );

double stix_get_cone_angle(
        stp_conical_surface * cone,
        RoseUnit as_is, 
        RoseUnit to_be
        );

The stix_get_cone_angle() function returns the semi angle of a cone and does unit conversion as needed. By default the angle is returned in radians, but you can specify degrees if desired. One of the overloads takes the enclosing representation and will find the angle unit from the representation context. The other overload takes an explicit enum value for the "as is" unit.

The function will return ROSE_NULL_REAL if the value is missing or if no unit conversion can be found. An unknown "as is" unit is assumed to be radians.

stix_get_direction_ijk()

void stix_get_direction_ijk (
	double ret[3],
	stp_cartesian_point * cp, 
	RoseXform * transform = 0
	);

void stix_get_direction_ijk (
	double &iret,
	double &jret,
	double &kret,
	stp_cartesian_point * cp, 
	RoseXform * transform = 0
	);

The stix_get_direction_ijk() function extracts direction components encoded as a cartesian point, which is supplied for tool axis and surface normal curves in STEP-NC. It normalizes the direction and applies an optional transformation matrix. Any missing components are zeroed out. If the direction is invalid because all components are zero, the function will set all of the return values to ROSE_NULL_REAL.

stix_get_edge_end()

stp_vertex * stix_get_edge_end(
        stp_edge * edge
        );
int stix_get_edge_end(
        double pt[3],
        stp_edge * edge
        );

The stix_get_edge_end() function returns the vertex instance that serves as the edge_end of an edge. When passed an oriented_edge, the function will returns the end of the nested edge_element.

The overload that takes an array of double will extract the coordinates from the vertex. It returns nonzero if values were found or zero on error.

stix_get_edge_start()

stp_vertex * stix_get_edge_start(
        stp_edge * edge
        );
int stix_get_edge_start(
        double pt[3],
        stp_edge * edge
        );

The stix_get_edge_start() function returns the vertex instance that serves as the edge_start of an edge. When passed an oriented_edge, the function will returns the start of the nested edge_element.

The overload that takes an array of double will extract the coordinates from the vertex. It returns nonzero if values were found or zero on error.

stix_get_point_xyz()

void stix_get_point_xyz (
	double ret[3],
	stp_cartesian_point * cp, 
	RoseUnit as_unit = roseunit_unknown,
	RoseUnit to_unit = roseunit_unknown
	);

void stix_get_point_xyz (
	double &xret,
	double &yret,
	double &zret,
	stp_cartesian_point * cp, 
	RoseUnit as_unit = roseunit_unknown,
	RoseUnit to_unit = roseunit_unknown
	);

void stix_get_point_xyz (
	double ret[3],
	stp_cartesian_point * cp, 
	RoseXform * transform,
	RoseUnit as_unit = roseunit_unknown,
	RoseUnit to_unit = roseunit_unknown
	);

void stix_get_point_xyz (
     	double &xret,
	double &yret,
	double &zret,
	stp_cartesian_point * cp, 
	RoseXform * transform,
	RoseUnit as_unit = roseunit_unknown,
	RoseUnit to_unit = roseunit_unknown
	);

The stix_get_point_xyz() function extracts the coordinate values from a cartesian point, optionally applies a transformation matrix, and then optionally converts the resulting coordinates to different units.

The transform is applied before any unit conversion, so if a matrix is given, it must be in the original units. If the cartesian point does not have enough coordinates, the missing values will be zeroed out. If a null pointer is passed for one of the return values, it will be ignored. If there is no conversion between the two given units (inches to degrees for example), the function will set all of the return values to ROSE_NULL_REAL.

stix_get_polyline_point()

stp_cartesian_point
* stix_get_polyline_point (
        stp_bounded_curve
        * bc, unsigned idx );

The stix_get_polyline_point() function is a convenience for working with a curve known to be a polyline. The arguments accept the polyline as a bounded curve and will perform any necessary casting to access the list of points within and will get the point at the given index. The stix_get_polyline_size() function returns the size of the list.

stix_get_polyline_size()

unsigned stix_get_polyline_size ( 
        stp_bounded_curve * bc
        );

The stix_get_polyline_size() function is a convenience for working with a curve known to be a polyline. The arguments accept the polyline as a bounded curve and will perform any necessary casting to return the size of the list of points within. The stix_get_polyline_point() function returns a cartesian point at a particular place in the polyline.

stix_get_styled_rep()

stp_representation * stix_get_styled_rep(
        stp_styled_item * si
        );

The stix_get_styled_rep() function returns the "item" field of a styled item as a representation pointer if the field contains a value of that type, or null otherwise. Originally, styled_item could only old a reference to a representation_item, but this was extended in AP242 by the addition of a SELECT type that can contain other types.

stix_get_styled_repitem()

stp_representation_item * stix_get_styled_repitem( 
        stp_styled_item * si
        );

The stix_get_styled_repitem() function returns the "item" field of a styled item as a representation_item pointer. If the value of that field is not a representation_item, the function returns null. This function simplifies work with styled items because newer schema versions change the "item" field to a SELECT type that can contain one of several different types of values.

stix_get_trimming_point()

stp_cartesian_point * stix_get_trimming_point (
        SetOfstp_trimming_select * tset
        );

The stix_get_trimming_point() function is a convenience function for working with STEP trim curves. Each end of a trimmed curve can be given as a cartesian point in XYZ space or as a parameter value T in terms of the curve equation. A trim curve may give one or both values, although the explicit point is almost universally used. This function looks at the set of trim values and returns the cartesian point if one is present, or NULL otherwise. 

stp_trimmed_curve * bc,

// an arc is encoded as a trimmed circle
stp_circle * circ = ROSE_CAST(stp_circle, bc->basis_curve());

// The start and end points of the arc
stp_cartesian_point * pt_start, pt_end;
pt_start = stix_get_trimming_point (bc->trim_1());
pt_end =   stix_get_trimming_point (bc->trim_2());

stix_make_ap3d()

stp_axis2_placement_3d * stix_make_ap3d(
        RoseDesign * d,
        const double xf[16],
        const char * name = 0
        );
stp_axis2_placement_3d * stix_make_ap3d(
        RoseDesign * d,
        const RoseXform& xf,
        const char * name = 0
        );

The stix_make_ap3d() function creates a new axis2_placement_3d instance in the given design and populates it with the origin, Z direction and X direction of the given transform. The object will have a name of "" if an optional name value is not supplied. 

RoseXform xf;  // an identity matrix by default

stp_axis2_placement_3d * ap = stix_make_ap3d(d, xf, "identity");


// The call above produces the following instance data
//
// #13=AXIS2_PLACEMENT_3D('identity',#19,#28,#29);
// #19=CARTESIAN_POINT('',(0.,0.,0.));
// #28=DIRECTION('',(0.,0.,1.));
// #29=DIRECTION('',(1.,0.,0.));

stix_make_cartesian_point()

stp_cartesian_point * stix_make_cartesian_point(
        RoseDesign * d,
        const double vec[3],
        const char * name = 0
        );
stp_cartesian_point * stix_make_cartesian_point(
        RoseDesign * d,
        const RosePoint& vec,
        const char * name = 0
        );

The stix_make_cartesian_point() function creates a new STEP cartesian point instance in the given design and populates it with all three coordinates. The object will have a name of "" if an optional name value is not supplied. 

RosePoint v1 (96, 97, 98);
double v2[3] = {0, 0, 0};

stp_cartesian_point * d1 = stix_make_cartesian_point(d, v1);
stp_cartesian_point * d2 = stix_make_cartesian_point(d, v2, "origin");


// The call above produces the following instance data
//
// #11=CARTESIAN_POINT('',(96.,97.,98.));
// #12=CARTESIAN_POINT('origin',(0.,0.,0.));

stix_make_cto3d()

stp_cartesian_transformation_operator_3d * stix_make_cto3d(
        RoseDesign * d,
        const double xf[16],
        const char * name = 0
        );
stp_cartesian_transformation_operator_3d * stix_make_cto3d(
        RoseDesign * d,
        const RoseXform& xf,
        const char * name = 0
        );

The stix_make_cto3d() function creates a new cartesian transformation operator instance in the given design and populates it with the origin, and all three axis directions of the given transform. The scale factor will always be one (1.0). The object will have a name of "" if an optional name value is not supplied. 

RoseXform xf;  // an identity matrix by default

stp_cartesian_transformation_operator_3d * cto = stix_make_cto3d(d, xf, "identity");


// The call above produces the following instance data
//
// #11=CARTESIAN_TRANSFORMATION_OPERATOR_3D('identity','',$,#33,#34,#21,1.,#35);
// #21=CARTESIAN_POINT('',(0.,0.,0.));
// #33=DIRECTION('',(1.,0.,0.));
// #34=DIRECTION('',(0.,1.,0.));
// #35=DIRECTION('',(0.,0.,1.));

stix_make_direction()

stp_direction * stix_make_direction(
        RoseDesign * d,
        const double vec[3],
        const char * name = 0
        );
stp_direction * stix_make_direction(
        RoseDesign * d,
        const RoseDirection& vec,
        const char * name = 0
        );

The stix_make_direction() function creates a new STEP direction instance in the given design and populates it with all three components. The components are used without change, so any normalization must be done before calling this function. The object will have a name of "" if an optional name value is not supplied. 

RoseDirection v1 (0, 1, 0);
double v2[3] = {4, 5, 6};

stp_direction * d1 = stix_make_direction(d, v1, "normalized");
stp_direction * d2 = stix_make_direction(d, v2, "not normalized");


// The call above produces the following instance data
//
// #34=DIRECTION('normalized',(0.,1.,0.));
// #35=DIRECTION('not normalized',(4.,5.,6.));

stix_put_styled_rep()

void stix_put_styled_rep( 
        stp_styled_item * si,
        stp_representation * rep
        );

The stix_put_styled_rep() function sets the "item" field of a styled item to a representation. This function simplifies work with styled items because newer schema versions change the "item" field to a SELECT type that can contain one of several different types of values.

stix_put_styled_repitem()

void stix_put_styled_repitem( 
        stp_styled_item * si,
        stp_representation_item * ri
        );

The stix_put_styled_repitem() function sets the "item" field of a styled item to a representation_item. This function simplifies work with styled items because newer schema versions change the "item" field to a SELECT type that can contain one of several different types of values.

stix_translate_geometry_units()

unsigned stix_translate_geometry_units (
        stp_representation * rep, 
        stp_representation_context * newctx
        );

The stix_translate_geometry_units() function converts all elements of a representation to the units in a new geometric context. If you have a ROSE traversal in process, the function will mark objects as they are converted, avoiding double conversion of shared points or surfaces. Note however, that if you only convert some of the representations and items are shared with a representation that is not converted, bad values could result.

stix_vec_put()

int stix_vec_put(
        double xyz[3],
        stp_cartesian_point * cpt
        );
int stix_vec_put(
        RosePoint& pt,
        stp_cartesian_point * cpt
        )

int stix_vec_put(
        double ijk[3],
        stp_direction * dir
        );
int stix_vec_put(
        RoseDirection& ijk,
        stp_direction * dir
        )

int stix_vec_put(
        double ijk[3],
        stp_vector * dir
        );
int stix_vec_put(
        RoseDirection& ijk,
        stp_vector * v
        )

int stix_vec_put(
        double xyz[3],
        stp_vertex * v
        );
int stix_vec_put(
        RosePoint& pt,
        stp_vertex * v
        )

The stix_vec_put() function is a STEP-specific version of the rose_vec_put() function. It extracts coordinate or direction data from a STEP object and assigns it to all three elements of an array, a RoseDirection, or a RosePoint. The function returns nonzero if the assignment succeeded or zero if there was a problem.

With a cartesian point, the coordinates list is extracted. If the point or coordinates list are null, or if the list does not contain enough coordinates, zero will be substituted for the missing values. The assignment will always succeed unless it is passed a null destination array. 

RosePoint dst_pt;
stp_cartesian_point * pt = get_some_point();

stix_vec_put(dst_pt, pt);

With a direction, the ratios list is extracted. If the direction or list are null, or if the list does not contain enough ratios, zero will be substituted for the missing values. The assignment will always succeed unless it is passed a null destination array. Use rose_vec_is_zero() to test for missing direction data. 

RoseDirection dst_dir;
stp_direction * dir = get_some_dir();

stix_vec_put(dst_dir, dir);
if (rose_vec_is_zero(dst_dir))
        printf ("MISSING DIRECTION DATA!!\n");

rose_vec_normalize(dst_dir);  // if you want normalized data

With a vector, the function will extract the orientation direction object. As above, use rose_vec_is_zero() to test for missing direction data. If you would like to completely capture the contents of the vector object, you can normalize the direction array and then scale it by the magnitude value. 

RoseDirection dst_dir;
stp_vector * vec = get_some_vec();

stix_vec_put(dst_dir, vec);
if (rose_vec_is_zero(dst_dir))
        printf ("MISSING DIRECTION DATA!!\n");

rose_vec_normalize(dst_dir);
rose_vec_scale(dst_dir, vec->magnitude());  // if you want the vector scaled

With a vertex, the function will cast it to a vertex_point and set the array from the cartesian point referenced as the vertex_geometry. The function will set the array to all zeros and the return zero to indicate error if the vertex is not a vertex_point, if the vertex_geometry is null, or if the vertex_geometry is not a cartesian_point. 

RosePoint dst_pt;
stp_vertex * vtx = get_some_topology();

if (!stix_vec_put(dst_pt, vtx))
        printf ("BAD VERTEX DATA!!\n");

stix_vec_put_as_unit()

int stix_vec_put_as_unit(
        double xyz[3],
        stp_cartesian_point * cpt, 
        RoseUnit as_is, 
        RoseUnit to_be
        );
int stix_vec_put_as_unit(
        RosePoint& pt,
        stp_cartesian_point * cpt,
        RoseUnit as_is, 
        RoseUnit to_be
        );

int stix_vec_put_as_unit(
        double xyz[3],
        stp_vertex * v, 
        RoseUnit as_is, 
        RoseUnit to_be
        );
int stix_vec_put_as_unit(
        RosePoint& pt,
        stp_vertex * v, 
        RoseUnit as_is, 
        RoseUnit to_be
        );

The stix_vec_put_as_unit() function is a extracts coordinates from STEP point data and does unit conversion as part of the assignment. The function takes two additional unit enum values that give the units governing the STEP data and the units desired for the result array. The function will return nonzero on success or zero on failure. In addition to the failure conditions of stix_vec_put(), the function will return zero if no conversion is defined between the two units.

This function simply wraps stix_vec_put() and rose_vec_put_as_unit().

stix_xform_put()

int stix_xform_put(
        double xf[16],
        stp_axis2_placement_3d * ap
        );
int stix_xform_put(
        RoseXform& xf,
        stp_axis2_placement_3d * ap
        );

int stix_xform_put(
        double xf[16],
        stp_axis2_placement * ap
        );
int stix_xform_put(
        RoseXform& xf,
        stp_axis2_placement * ap
        );

int stix_xform_put(
        double xf[16],
        stp_axis1_placement * ap
        );
int stix_xform_put(
        RoseXform& xf,
        stp_axis1_placement * ap
        );

int stix_xform_put(
        double xf[16],
        stp_cartesian_transformation_operator * cto
        );
int stix_xform_put(
        RoseXform& xf,
        stp_cartesian_transformation_operator * cto
        );

The stix_xform_put() function extracts coordinates and axis directions from STEP placement or transform data and constructs a RoseXform or array of sixteen doubles. The function returns nonzero if the assignment succeeded or zero if there was a problem.

When assigning an axis placement, the result will be a normalized, right-handed, orthogonal matrix with all defaults handled properly as with rose_xform_put_dirs().

When assigning an cartesian transformation operator, the result will be normalized during construction but may then have a scaling factor applied. It is also possible for a CTO to encode a left-handed coordinate system. This function simply extracts the data from the STEP instance — the assignment is performed by by rose_xform_put_cto().

Copyright © 2024 STEP Tools Inc. All Rights Reserved.