STEP Representations and Items

Overview

A STEP representation describes the value of a property. Geometric shape is the most common property. A representation contains a set of representation items and a context.

The representation items for shape will contain geometry and axis placements. A context gives the units for geometry. Other properties may have measure values, such as the surface area and volume properties used to verify shape exchange.

Axis Placements and Geometry

The items in a shape representation are all geometric or topologic representation item subtypes. The set typically contains a solid_model or axis2_placement_3d instances for positioning.

The "xform" and "vec" functions interface axis placements, directions, and points with the ROSE transform and vector operations. For example, stix_xform_put() extracts coordinates and axis directions from STEP placement or transform data, normalizes everything and puts the values into an array of sixteen doubles or RoseXform. The stix_vec_put() puts values from a cartesian point, direction, and similar types into an array of three doubles.

Other functions simplify work with polylines, trim curves, and other geometry.

Contexts and Units

The STEP geometry definitions are unitless, so additional information is provided by a representation context that describes the units for geometry, the number of dimensions (2D or 3D) and an uncertainty value for comparing points.

The stix_rep_angle_unit() and stix_rep_length_unit() functions get the units from a context. By convention, contexts also define a solid angle unit although this is always "steradian". The stix_rep_make_context() function creates a representation context, which requires some ANDOR type combinations.

The STEP unit functions create or recognize STEP unit definitions as a simple enum for easy programming.

The geometric uncertainty is is the distance below which two points should be considered the same. It is important when exchanging geometry between systems that work at different precisions. The stix_rep_uncertainty() functions returns the uncertainty declared by a context.

STEP files sometimes contain repeated context information, such as three or four geometry contexts that declare the same units and possibly the same uncertainty values. The stix_rep_merge_contexts() function can combine duplicate contexts.

stp_representation * rep;
RoseUnit lu = stix_rep_length_unit(rep);
RoseUnit au = stix_rep_angle_unit(rep);

printf(Length unit: %s\n, rose_unit_name(lu));
printf(Plane angle unit: %s\n, rose_unit_name(au));

Measure Values

A representation may describe a numeric quantity like surface area, pressure, or time as a measure with unit representation item. The stix_rep_find_measure_item() function searches the items of a representation for a specific kind of measure. Versions of this function specialize in angle, count, linear speed, length, pressure, ratio, rotational speed, and time values.

The STEP measure functions create or extract the details of a measure description. Get the numeric value of a measure with stix_measure_get_value(). Specialized versions exist for angle, count, etc. Qualified measures may also have an upper limit, lower limit, or precision value.

A measure carries its own unit which you can get with stix_unit_get_type() and the other STEP unit functions.

stix_cone_get_angle()

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

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

The stix_cone_get_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_edge_get_end()

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

The stix_edge_get_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_edge_get_start()

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

The stix_edge_get_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_polyline_get_point()

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

The stix_polyline_get_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_polyline_get_size() function returns the size of the list.

stix_polyline_get_size()

unsigned stix_polyline_get_size ( 
        stp_bounded_curve * bc
        );

The stix_polyline_get_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_polyline_get_point() function returns a cartesian point at a particular place in the polyline.

stix_rep_angle_unit()

RoseUnit stix_rep_angle_unit(
        stp_representation * rep
        );
RoseUnit stix_rep_angle_unit(
        stp_representation_context * ctx
        );

The stix_rep_angle_unit() function returns the plane angle unit defined by a geometric context, or roseunit_unknown if the context does not define a plane angle unit. This function is a convenience wrapper that calls stix_rep_find_unit() to find the unit.

stix_rep_find_angle_item()

stp_measure_representation_item * stix_rep_find_angle_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_angle_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure item that holds a plane angle measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_count_item()

stp_measure_representation_item * stix_rep_find_count_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_count_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure item that holds a count measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_descriptive_item()

stp_descriptive_representation_item * stix_rep_find_descriptive_item (
        stp_representation * rep, 
        const char * desired_name
        );

The stix_rep_find_descriptive_item() function is a wrapper around stix_rep_find_item() that searches the items set of a representation to find a descriptive representation item. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_feedrate_item()

stp_measure_representation_item * stix_rep_find_feedrate_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_feedrate_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure representation item that holds a linear speed measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_item()

stp_representation_item * stix_rep_find_item (
        stp_representation * rep, 
        RoseDomain * targ_type, 
        const char * targ_name
        );

The stix_rep_find_item() function searches the items set within a representation for a representation_item that matches the EXPRESS type given by "targ_type". If "targ_name" is not null, the item must also have that string as the rep item name. This is more general than stix_rep_find_measure_item() because it works on any type of representation item.

stix_rep_find_length_item()

stp_measure_representation_item * stix_rep_find_length_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_length_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure representation item that holds a length measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_measure_item()

stp_measure_representation_item * stix_rep_find_measure_item(
        stp_representation * rep, 
        const char *  desired_name, 
        RoseMeasureType desired_mt
        );

The stix_rep_find_measure_item() function searches the items set within a representation for a measure that matches the type of value given by "desired_mt". If "desired_name" is not null, the measure must also have that string as the rep item name.

stp_representation * some_rep;

stp_measure_representation_item * mri = 
    stix_rep_find_measure_item (some_rep, box height, rosemeasure_length);

stix_rep_find_nested_items()

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

The stix_rep_find_nested_items() 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_rep_find_pressure_item()

stp_measure_representation_item * stix_rep_find_pressure_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_pressure_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure representation item that holds a pressure measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_ratio_item()

stp_measure_representation_item * stix_rep_find_ratio_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_ratio_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure representation item that holds a ratio measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_spinrate_item()

stp_measure_representation_item * stix_rep_find_spinrate_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_spinrate_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure representation item that holds a rotational speed measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_time_item()

stp_measure_representation_item * stix_rep_find_time_item (
        stp_representation * rep, 
        const char * desired_name = 0
        );

The stix_rep_find_time_item() function is a wrapper around stix_rep_find_measure_item() that searches the items set of a representation to find a measure representation item that holds a time measure. If the desired_name parameter is not null, the name attribute of the representation item must also match it exactly.

stix_rep_find_unit()

RoseUnit stix_rep_find_unit (
        stp_representation_context * ctx,
        RoseMeasureType mt
        );

RoseUnit stix_rep_find_unit (
        stp_representation * rep, 
        RoseMeasureType mt
        );


stp_unit * stix_rep_find_unit_item (
        stp_representation_context * ctx,
        RoseMeasureType mt
	);

The stix_rep_find_unit() function searches a representation context for a particular kind of unit definition. The function returns roseunit_unknown if the context is not an instance of global_unit_assigned_context or does not contain a unit of the given type.

The stix_rep_angle_unit(), stix_rep_length_unit(), and stix_rep_solid_angle_unit() functions are convenience wrappers for the units commonly found in geometric contexts.

The stix_rep_find_unit_item() version returns the stp_unit SELECT object containing the STEP unit definition.

stix_rep_length_unit()

RoseUnit stix_rep_length_unit(
        stp_representation * rep
        );
RoseUnit stix_rep_length_unit(
        stp_representation_context * ctx
        );

The stix_rep_length_unit() function returns the length unit defined by a geometric context, or roseunit_unknown if the context does not define a length unit. This function is a convenience wrapper that calls stix_rep_find_unit() to find the unit.

stix_rep_make_context()

stp_representation_context * stix_rep_make_context(
        RoseDesign * design,
        const char * id,
        unsigned dims,
        stp_named_unit * len_unit,
        stp_named_unit * ang_unit,
        stp_named_unit * solid_ang_unit,
        double length_uncertainty = ROSE_NULL_REAL
        );

stp_representation_context * stix_rep_make_context(
        RoseDesign * design,
        const char * id,
        unsigned dims,
        RoseUnit len_unit,
        RoseUnit ang_unit,
        RoseUnit solid_ang_unit,
        double length_uncertainty = ROSE_NULL_REAL
        );

stp_representation_context * stix_rep_make_context(
        RoseDesign * design,
        const char * id,
        unsigned dims,
        RoseUnitSet units,
        double length_uncertainty = ROSE_NULL_REAL
        );

The stix_rep_make_context() function creates a representation context for geometric information. Geometry contexts give the number of dimensions (usually 3), units for length, angle, and solid angle, and often a global uncertainty measure for comparing point locations. This information is held by a single representation context object that is a complex instance of the following subtypes:

geometric_representation_context
global_unit_assigned_context
global_uncertainty_assigned_context (if an uncertainty is given)

There are three overloaded versions of this function. The first takes pointers for the unit objects. The second takes RoseUnit enums for the units and creates them by calling stix_unit_make_named() The third takes a RoseUnitSet object and uses the length, angle, and solid angle fields within it.

stix_rep_merge_contexts()

unsigned stix_rep_merge_contexts(
	RoseDesign * d
 	);

The stix_rep_merge_contexts() function examines all of the representation contexts in a file, moves duplicates to the trash and registers the primary context as a substitute. The function returns the number of duplicates that were merged. If non-zero, call rose_empty_trash() to update the pointers and delete the duplicates.

STEP files sometimes contain duplicate representation contexts, say three or four contexts that declare the same units and possibly the same uncertainty values. This function is used to compact that excess data down to a single context instance.

When merging contexts that are the same except for geometric uncertainty values, the function will merge uncertainties that are within 1% of each other, so 1.99E-5 and 2E-5 will merge with the slightly larger uncertainty (2E-5) surviving.

For non-geometric contexts (instances of the representation context supertype), the function will merge instances with matching context type fields. The context type field is ignored when combining the geometric context subtypes. The stix_unit_merge() function performs a similar compaction for the unit definitions.

RoseDesign * d = ...

unsigned modcnt = stix_rep_merge_contexts(d);
if (modcnt) {
    printf (Merged %d duplicate contexts\n, modcnt);
    rose_empty_trash();

    // Could call rose_update_object_references(d) instead
    // of emptying the trash.   Only updates pointers in one 
    // design and does not delete the trashed objects.
}

stix_rep_solid_angle_unit()

RoseUnit stix_rep_solid_angle_unit(
        stp_representation * rep
 	);
RoseUnit stix_rep_solid_angle_unit(
        stp_representation_context * ctx
        );

The stix_rep_solid_angle_unit() function returns the solid angle unit defined by a geometric context, or roseunit_unknown if the context does not define a solid angle unit. This function is a convenience wrapper that calls stix_rep_find_unit() to find the unit.

stix_rep_translate_geometry_units()

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

The stix_rep_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_rep_uncertainty()

double stix_rep_uncertainty_value (
	stp_representation * rep
	);

double stix_rep_uncertainty_value (
        stp_representation_context * ctx
        );

stp_uncertainty_measure_with_unit * stix_rep_uncertainty_item (
        stp_representation * rep,
        const char * uncert_name = 0
        );

stp_uncertainty_measure_with_unit * stix_rep_uncertainty_item (
        stp_representation_context * ctx, 
        const char * uncert_name = 0
        );

The stix_rep_uncertainty() function returns an uncertainty value from a geometric context. The "item" version returns the measure representation item that holds the value. The value will be in the length unit given by the context. If no uncertainty is present, a default value of 1e-8 is returned.

The uncertainty represents the distance below which two points should be considered the same. This is an important concept when exchanging geometry because CAD systems work at different precisions. Knowing what the original system considered too small to distinguish lets a receiving system compensate for that, even if it works at a higher precision.

Multiple uncertainties and uncertainties for things other than lengths are possible but not used in practice. If you want to look for an uncertainty with a specific name, use the "item" version and get the value with the measure functions.

stix_trim_get_point()

stp_cartesian_point * stix_trim_get_point (
        SetOfstp_trimming_select * tset
        );

The stix_trim_get_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_trim_get_point (bc->trim_1());
pt_end =   stix_trim_get_point (bc->trim_2());

stix_vec_make_direction()

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

The stix_vec_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_vec_make_direction(d, v1, normalized);
stp_direction * d2 = stix_vec_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_vec_make_point()

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

The stix_vec_make_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_vec_make_point(d, v1);
stp_cartesian_point * d2 = stix_vec_make_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_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
        )



/* ----- 2D variations ----- */
int stix_vec2d_put(
        double xy[2],
        stp_cartesian_point * cpt
        );
int stix_vec2d_put(
        RosePoint2D& pt,
        stp_cartesian_point * cpt
        )

int stix_vec2d_put(
        double ij[2],
        stp_direction * dir
        );
int stix_vec2d_put(
        RoseDirection2D& ij,
        stp_direction * dir
        )

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. The stix_vec2d_put() versions extract a 2D result.

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_direction()

int stix_vec_put_as_direction(
	double ret[3],
	stp_cartesian_point * cp, 
	const double * xf = 0
	);

The stix_vec_put_as_direction() function extracts direction components encoded as a cartesian point in STEP-NC 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_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 ret[3],
        stp_cartesian_point * cpt, 
	const double xf[16],
        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().

If a transform is given, it will be applied before any unit conversion, so it must be in the original units. If the cartesian point does not have enough coordinates, the missing values will be zeroed out.

stix_xform_make_ap3d()

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

The stix_xform_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_xform_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_xform_make_cto3d()

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

The stix_xform_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_xform_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_xform_put()

int stix_xform_put(double xf[16], stp_placement * ap);
int stix_xform_put(RoseXform& xf, stp_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_axis2_placement_2d * ap);
int stix_xform_put(RoseXform& xf, stp_axis2_placement_2d * ap);

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_cartesian_transformation_operator * cto);
int stix_xform_put(RoseXform& xf, stp_cartesian_transformation_operator * cto);


/* ----- 2D variations ----- */
int stix_xform2d_put(double xf[9],    stp_axis2_placement_2d * ap);
int stix_xform2d_put(RoseXform2D& xf, stp_axis2_placement_2d * ap);

int stix_xform2d_put(double xf[9],    stp_axis2_placement_3d * ap);
int stix_xform2d_put(RoseXform2D& xf, stp_axis2_placement_3d * ap);

int stix_xform2d_put(double xf[9],    stp_axis2_placement * ap);
int stix_xform2d_put(RoseXform2D& xf, stp_axis2_placement * ap);

int stix_xform2d_put(double xf[9],    stp_axis1_placement * ap);
int stix_xform2d_put(RoseXform2D& xf, stp_axis1_placement * ap);

int stix_xform2d_put(double xf[9],    stp_cartesian_transformation_operator * cto);
int stix_xform2d_put(RoseXform2D& xf, stp_cartesian_transformation_operator * cto);

The stix_xform_put() function extracts coordinates and axis directions from STEP placement or transform data and constructs an array of sixteen doubles or a RoseXform wrapper class. The function returns nonzero if the assignment succeeded or zero if there was a problem. If a 2D axis placement is provided, the result will be a 3D transform at Z=0 with the default Z direction.

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().

The stix_xform2d_put() functions build a 3x3 transform matrix as an array of nine doubles or a RoseXform2D wrapper class.

A 3D axis placement can be provided to the 2D function. The resulting 2D matrix will be built with the given X direction. This will have similar XY directions if the Z direction is positive, but will flip the Y direction to maintain a right hand coordinate system if the original 3D placement had a negative Z direction.